Documentation: Database.query methods share docstrings (#13515)

Currently, query arguments in the Spack core are documented on the
Database._query method, where the functionality is defined.

For users of the spack python command, this makes the python builtin
method help less than ideally useful, as help(spack.store.db.query)
and help(spack.store.db.query_local) do not show relevant information.

This PR updates the doc attributes for the Database.query and
Database.query_local arguments to mirror everything after the first
line of the Database._query docstring.

1 files changed, 53 insertions, 41 deletions

diff --git a/lib/spack/spack/database.py b/lib/spack/spack/database.py
index a1748fc585..e6e82f9803 100644
--- a/lib/spack/spack/database.py
+++ b/lib/spack/spack/database.py
@@ -206,6 +206,50 @@ class ForbiddenLock(object):
             "Cannot access attribute '{0}' of lock".format(name))
 
 
+_query_docstring = """
+
+        Args:
+            query_spec: queries iterate through specs in the database and
+                return those that satisfy the supplied ``query_spec``. If
+                query_spec is `any`, This will match all specs in the
+                database.  If it is a spec, we'll evaluate
+                ``spec.satisfies(query_spec)``
+
+            known (bool or any, optional): Specs that are "known" are those
+                for which Spack can locate a ``package.py`` file -- i.e.,
+                Spack "knows" how to install them.  Specs that are unknown may
+                represent packages that existed in a previous version of
+                Spack, but have since either changed their name or
+                been removed
+
+            installed (bool or any, or InstallStatus or iterable of
+                InstallStatus, optional): if ``True``, includes only installed
+                specs in the search; if ``False`` only missing specs, and if
+                ``any``, all specs in database. If an InstallStatus or iterable
+                of InstallStatus, returns specs whose install status
+                (installed, deprecated, or missing) matches (one of) the
+                InstallStatus. (default: True)
+
+            explicit (bool or any, optional): A spec that was installed
+                following a specific user request is marked as explicit. If
+                instead it was pulled-in as a dependency of a user requested
+                spec it's considered implicit.
+
+            start_date (datetime, optional): filters the query discarding
+                specs that have been installed before ``start_date``.
+
+            end_date (datetime, optional): filters the query discarding
+                specs that have been installed after ``end_date``.
+
+            hashes (container): list or set of hashes that we can use to
+                restrict the search
+
+        Returns:
+            list of specs that match the query
+
+        """
+
+
 class Database(object):
 
     """Per-process lock objects for each install prefix."""
@@ -1158,48 +1202,8 @@ class Database(object):
             end_date=None,
             hashes=None
     ):
-        """Run a query on the database
+        """Run a query on the database."""
 
-        Args:
-            query_spec: queries iterate through specs in the database and
-                return those that satisfy the supplied ``query_spec``. If
-                query_spec is `any`, This will match all specs in the
-                database.  If it is a spec, we'll evaluate
-                ``spec.satisfies(query_spec)``
-
-            known (bool or any, optional): Specs that are "known" are those
-                for which Spack can locate a ``package.py`` file -- i.e.,
-                Spack "knows" how to install them.  Specs that are unknown may
-                represent packages that existed in a previous version of
-                Spack, but have since either changed their name or
-                been removed
-
-            installed (bool or any, or InstallStatus or iterable of
-                InstallStatus, optional): if ``True``, includes only installed
-                specs in the search; if ``False`` only missing specs, and if
-                ``any``, all specs in database. If an InstallStatus or iterable
-                of InstallStatus, returns specs whose install status
-                (installed, deprecated, or missing) matches (one of) the
-                InstallStatus. (default: True)
-
-            explicit (bool or any, optional): A spec that was installed
-                following a specific user request is marked as explicit. If
-                instead it was pulled-in as a dependency of a user requested
-                spec it's considered implicit.
-
-            start_date (datetime, optional): filters the query discarding
-                specs that have been installed before ``start_date``.
-
-            end_date (datetime, optional): filters the query discarding
-                specs that have been installed after ``end_date``.
-
-            hashes (container): list or set of hashes that we can use to
-                restrict the search
-
-        Returns:
-            list of specs that match the query
-
-        """
         # TODO: Specs are a lot like queries.  Should there be a
         # TODO: wildcard spec object, and should specs have attributes
         # TODO: like installed and known that can be queried?  Or are
@@ -1246,11 +1250,17 @@ class Database(object):
 
         return results
 
+    _query.__doc__ += _query_docstring
+
     def query_local(self, *args, **kwargs):
+        """Query only the local Spack database."""
         with self.read_transaction():
             return sorted(self._query(*args, **kwargs))
 
+    query_local.__doc__ += _query_docstring
+
     def query(self, *args, **kwargs):
+        """Query the Spack database including all upstream databases."""
         upstream_results = []
         for upstream_db in self.upstream_dbs:
             # queries for upstream DBs need to *not* lock - we may not
@@ -1265,6 +1275,8 @@ class Database(object):
 
         return sorted(results)
 
+    query.__doc__ += _query_docstring
+
     def query_one(self, query_spec, known=any, installed=True):
         """Query for exactly one spec that matches the query spec.