Update documentation for all the functions and make sure it reflects reality

Is this change intentional? It's not a documentation change, and has broken a couple of my facets (single value taxonomy fields).

@@ -1973,7 +1982,7 @@ function apachesolr_entity_fields($entity_type = 'node') {
           'facet missing allowed' => FALSE,
           'facet mincount allowed' => FALSE,
           // Field API allows any field to be multi-valued.
-          'multiple' => TRUE,
+          'multiple' => FALSE,
         );
       if ($key !== 'per-field') {
         $mappings[$key] += $defaults;

I've proposed a fix for the facets this broke at http://drupal.org/node/1979506

needs to eb backported?

setting back to needs work. I think @ianmthomasuk is correct in #12 that the change to the field mappings was a mistake.

Even if it was committed accidentally, I think the behaviour in 1.2 makes sense and has the benefit that you can sort by the single-value field. The only exception I know about is taxonomy fields, which is addressed in https://drupal.org/node/1979506

@ianmthomasuk - I thought we were already adding a single value version (the 1st value) for every field when indexing?

@pwolanin That's not what happens on my site, using 1.1 plus a few patches that shouldn't change that behaviour.

@ianmthomasuk - check your index. It's possible we are not exposing that as a sort in the UI, but it should be there.

See apachesolr.index.inc:

    // Also store the first value of the field in a singular index for multi value fields
    if ($field_info['multiple'] && $numeric && !empty($values[0])) {
      $singular_field_info = $field_info;
      $singular_field_info['multiple'] = FALSE;
      $single_key = apachesolr_index_key($singular_field_info);
      $fields[] = array(
        'key' => $single_key,
        'value' => $function($values[0]['value']),
      );
    }

Here a patch reverting that change, plus a minor cleanup.

I've been having a discussion with @pwolanin on IRC about the merits of this patch and whether it's desirable to attempt to index a multi-value Drupal field as a single value Solr field.

Benefits:
* You can change the cardinality of the field without re-indexing
* You can sort on the field

Drawbacks:
* The sort order can be inconsistent, as it depends on the order of the values in the multi-value field (e.g. if you have two nodes with multi-value price fields of (29.99, 19.99) and (24.99, 34.99) and you sorted by price asc then the second node would be listed first, when you probably wanted to sort by minimum price or maximum price).
* Slightly increases index size / indexing time

I'm marking this RTBC as an all-singing all-dancing solution would take quite a lot of work, and this at least resolves the regression for people upgrading from <1.1. It does need a release note to warn users of 1.2 that some of their fields will change back to their old names.

committed