[#2345] Docstring for package_search action.

ckan/logic/action/get.py

@@ -837,6 +837,95 @@ def user_autocomplete(context, data_dict):
     return user_list
 
 def package_search(context, data_dict):
+    '''
+    Searches for packages satisfying a given search criteria.
+
+    This action accepts solr search query parameters (details below), and
+    returns a dictionary of results, including dictized datasets that match
+    the search criteria, a search count and also facet information.
+
+    Solr Parameters:
+
+    For more in depth treatment of each paramter, please read the `Solr
+    Documentation <http://wiki.apache.org/solr/CommonQueryParameters>`_.
+
+    This action accepts a *subset* of solr's search query parameters:
+
+    :param q: the solr query.  Optional.  Default: `"*:*"`
+    :type q: string
+    :param fq: any filter queries to apply.  Note: `+site_id:{ckan_site_id}`
+        is added to this string prior to the query being executed.
+    :type fq: string
+    :param rows: the number of matching rows to return.
+    :type rows: int
+    :param sort: sorting of the search results.  Optional.  Default:
+        "score desc, name asc".  As per the solr documentation, this is a
+        comma-separated string of field names and sort-orderings.
+    :type sort: string
+    :param start: the offset in the complete result for where the set of
+        returned datasets should begin.
+    :type start: int
+    :param qf: the dismax query fields to search within, including boosts.  See
+        the `Solr Dismax
+        Documentation<http://wiki.apache.org/solr/DisMaxQParserPlugin#qf_.28Query_Fields.29>`_
+        for further details.
+    :type qf: string
+    :param facet: whether to enable faceted results.  Default: "true".
+    :type facet: string
+    :param facet.mincount: the minimum counts for facet fields should be
+        included in the results.
+    :type facet.mincount: int
+    :param facet.limit: the maximum number of constraint counts that should be
+        returned for the facet fields. A negative value means unlimited
+    :type facet.limit: int
+    :param facet.field: the fields to facet upon.  Default empty.  If empty,
+        then the returned facet information is empty.
+    :type facet.field: list of strings
+
+    Results:
+
+    The result of this action is a dict with the following keys:
+
+    :param count: the number of results found.  Note, this is the total number
+        of results found, not the total number of results returned (which is
+        affected by limit and row parameters used in the input).
+    :type count: int
+    :param results: ordered list of datasets matching the query, where the
+        ordering defined by the sort parameter used in the query.
+    :type results: list of dictized datasets.
+    :param search_facets: aggregated information about facet counts.  The outer
+        dict is keyed by the facet field name (as used in the search query).
+        Each entry of the outer dict is itself a dict, with a "title" key, and
+        an "items" key.  The "items" key's value is a list of dicts, each with
+        "count", "display_name" and "name" entries.  The display_name is a
+        form of the name that can be used in titles.
+    :type search_facets: nested dict of dicts.
+
+    An example result: ::
+
+     {'count': 2,
+      'results': [ { <snip> }, { <snip> }],
+      'search_facets': {u'tags': {'items': [{'count': 1,
+                                             'display_name': u'tolstoy',
+                                             'name': u'tolstoy'},
+                                            {'count': 2,
+                                             'display_name': u'russian',
+                                             'name': u'russian'}
+                                           ]
+                                 }
+                       }
+     }
+
+    Limitations:
+
+    The full solr query language is not exposed, including.
+
+    fl
+        The parameter that controls which fields are returned in the solr
+        query cannot be changed.  CKAN always returns the matched datasets as
+        dictionary objects.
+
+    '''
     model = context['model']
     session = context['session']
     user = context['user']