The documentation for hook_ranking() is wrong

I just spent the last couple hours trying to figure out why I was getting a non-sensical SQL error during searches. While looking into it, I finally discovered that the problem is that the documentation for hook_ranking() (both D7 and D8) has incorrect instructions (and example) for how to use the 'join' key. It says that the 'join' value should be a string that will be merged into the SQL query, when in fact it needs to be an array of values, like below:

'join' => array(
  'type' => 'LEFT',
  'table' => 'node_counter',
  'alias' => 'node_counter',
  'on' => 'node_counter.nid = i.sid',
)

I discovered this by looking through core for implementations of hook_ranking() that use the 'join' key, and found one in statistics.module. That led me to finally understand what's happening in node.module's _node_rankings() function, and why that array is needed.

My guess is that at some point in the development process for the ranking hook system, the 'join' key was changed to an array, but the documentation was never updated.

Beta phase evaluation