Add a bit more ESQuery documentation

corehq/apps/es/es_query.py

@@ -143,10 +143,8 @@ def __init__(self, index=None):
     @property
     def builtin_filters(self):
         """
-        A list of callables that return filters
-        These will all be available as instance methods, so you can do
-        ``self.term(field, value)``
-        instead of
+        A list of callables that return filters. These will all be available as
+        instance methods, so you can do ``self.term(field, value)`` instead of
         ``self.filter(filters.term(field, value))``
         """
         return [
@@ -174,7 +172,7 @@ def add_filter(*args, **kwargs):
         raise AttributeError("There is no builtin filter named %s" % attr)
 
     def run(self):
-        """Actually run the query.  Return an ESQuerySet object."""
+        """Actually run the query.  Returns an ESQuerySet object."""
         raw = run_query(self.url, self.raw_query)
         return ESQuerySet(raw, deepcopy(self))
 
@@ -296,6 +294,7 @@ def remove_default_filters(self):
         return query
 
     def remove_default_filter(self, default):
+        """Remove a specific default filter by passing in its name."""
         query = deepcopy(self)
         if default in query._default_filters:
             query._default_filters.pop(default)
@@ -327,10 +326,12 @@ def raw_hits(self):
 
     @property
     def doc_ids(self):
+        """Return just the docs ids from the response."""
         return [r['_id'] for r in self.raw_hits]
 
     @property
     def hits(self):
+        """Return the docs from the response."""
         if self.query._fields == []:
             return self.ids
         elif self.query._fields is not None:
@@ -340,6 +341,7 @@ def hits(self):
 
     @property
     def total(self):
+        """Return the total number of docs matching the query."""
         return self.raw['hits']['total']
 
     @property
@@ -356,6 +358,10 @@ def facet(self, name, _type):
     @property
     @memoized
     def facets(self):
+        """
+        Namedtuple of the facets defined in the query.
+        See the facet docs for more specifics.
+        """
         facets = self.query._facets
         raw = self.raw.get('facets', {})
         results = namedtuple('facet_results', [f.name for f in facets])

corehq/apps/es/queries.py

@@ -1,10 +1,20 @@
+"""
+Available Queries
+-----------------
+
+Queries are used for actual searching - things like relevancy scores,
+Levenstein distance, and partial matches.
+
+View the `elasticsearch documentation <query_docs>`_ to see what other options
+are available, and put 'em here if you end up using any of 'em.
+
+.. _`query_docs`: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-queries.html
+"""
 import re
 
 
 def match_all():
-    """
-    No-op query used because a default must be specified
-    """
+    """No-op query used because a default must be specified"""
     return {"match_all": {}}
 
 
@@ -21,9 +31,11 @@ def _smart_query_string(search_string):
 
 def search_string_query(search_string, default_fields=None):
     """
-    If search_string does not use the ES query string syntax,
-    default to doing an infix search for each term.
-    returns (is_simple, query)
+    Allows users to use advanced query syntax, but if ``search_string`` does
+    not use the ES query string syntax, default to doing an infix search for
+    each term.  (This may later change to some kind of fuzzy matching).
+
+    This is also available via the main ESQuery class.
     """
     if not search_string:
         return match_all()