Search API is inconsistent in $type/$module, and generally needs doc cleanup

Just as a note, we'd like to wait for #567100: Search module is assuming node is default search even when it's disabled to land before attacking this one.

Working on a patch...

Uh oh. Never let jhodgdon get into a clean-up issue... This patch got a bit large, but the doc headers for the search module were in rather a mess. This patch fixes them up considerably.

Note that I left the search_expression_insert/extract functions alone, as they are being addressed in another issue.

The actual fixes could take weeks/months to get in. I'm tired of postponing everything...

#9: 0001-Search-API-is-inconsistent-in.patch queued for re-testing.

Just as a note, I actually wrote the original to the patch in #9, so if someone else could review it, that would be helpful. It's all documentation though (no code changes except changing names of local variables), so it can wait until a less frantic time.

I don't think we can do anything about that line. Here's the context:

  /**
-   * Search items for the given search query string and type.
+   * Sets up the search query expression.
    *
    * @param $query
-   *   A search query string, that can contain options.
-   * @param $type
-   *   The type of search, this maps to {search_index}.type.
+   *   A search query string, which can contain options.
+   * @param $module
+   *   The search module. This maps to {search_index}.type in the database.
+   *
    * @return
    *   The SearchQuery object.
    */
-  public function searchExpression($expression, $type) {
+  public function searchExpression($expression, $module) {
     $this->searchExpression = $expression;
-    $this->type = $type;
+    $this->type = $module;
 
     return $this;
   }

I really don't want to change the APIs at this point (except for local variable and param names, which have no real effect on the API or code). This is inside the search query extender class, and the variable was called $type a long time ago, and I don't think we should go back and change it now.