DM-46178: Documentation fixes for new query system

python/lsst/daf/butler/_butler_config.py

@@ -25,8 +25,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Configuration classes specific to the Butler.
-"""
+"""Configuration classes specific to the Butler."""
 from __future__ import annotations
 
 __all__ = ("ButlerConfig",)

python/lsst/daf/butler/_dataset_association.py

@@ -72,10 +72,11 @@ def from_query_result(
 
         Parameters
         ----------
-        result : `GeneralQueryResults`
-            General query result returned by `Query.general` method. The result
-            has to include "{dataset_type.name}.timespan" and
-            "{dataset_type.name}.collection" columns.
+        result : `~lsst.daf.butler.queries.GeneralQueryResults`
+            General query result returned by
+            `Query.general <lsst.daf.butler.queries.Query.general>` method. The
+            result has to include "dataset_id", "run", "collection", and
+            "timespan" dataset fields for ``dataset_type``.
         dataset_type : `DatasetType`
             Dataset type, query has to include this dataset type.
         """

python/lsst/daf/butler/_deferredDatasetHandle.py

@@ -25,8 +25,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Module containing classes used with deferring dataset loading.
-"""
+"""Module containing classes used with deferring dataset loading."""
 from __future__ import annotations
 
 __all__ = ("DeferredDatasetHandle",)

python/lsst/daf/butler/queries/_base.py

@@ -41,16 +41,17 @@
 
 
 class QueryBase(ABC):
-    """Common base class for `Query` and all `QueryResult` objects.
+    """Common base class for `~lsst.daf.butler.queries.Query` and all
+    ``QueryResult`` objects.
 
     This class should rarely be referenced directly; it is public only because
     it provides public methods to its subclasses.
 
     Parameters
     ----------
-    driver : `QueryDriver`
+    driver : `~lsst.daf.butler.queries.driver.QueryDriver`
         Implementation object that knows how to actually execute queries.
-    tree : `QueryTree`
+    tree : `~lsst.daf.butler.queries.tree.QueryTree`
         Description of the query as a tree of joins and column expressions.
     """
 
@@ -113,8 +114,11 @@ def where(
         ----------
         *args
             Constraints to apply, combined with logical AND.  Arguments may be
-            `str` expressions to parse, `Predicate` objects (these are
-            typically constructed via `expression_factory`) or data IDs.
+            `str` expressions to parse,
+            `~lsst.daf.butler.queries.tree.Predicate` objects (these are
+            typically constructed via
+            `Query.expression_factory <lsst.daf.butler.queries.Query.expression_factory>`)
+            or data IDs.
         bind : `~collections.abc.Mapping`
             Mapping from string identifier appearing in a string expression to
             a literal value that should be substituted for it.  This is
@@ -134,15 +138,15 @@ def where(
 
         Notes
         -----
-        If an expression references a dimension or dimension element that is
-        not already present in the query, it will be joined in, but dataset
-        searches must already be joined into a query in order to reference
-        their fields in expressions.
+        Expressions referring to dimensions or dimension elements are resolved
+        automatically. References to dataset fields (see `expression_factory`
+        for the distinction) may or may not be resolvable, depending on the
+        implementation class.
 
         Data ID values are not checked for consistency; they are extracted from
         ``args`` and then ``kwargs`` and combined, with later values overriding
         earlier ones.
-        """
+        """  # noqa: W505, long docstrings
         raise NotImplementedError()
 
 

python/lsst/daf/butler/queries/_general_query_results.py

@@ -111,6 +111,9 @@ def iter_tuples(self, *dataset_types: DatasetType) -> Iterator[GeneralResultTupl
         """Iterate over result rows and return data coordinate, and dataset
         refs constructed from each row, and an original row.
 
+        This object has to include "dataset_id" and "run" columns for each type
+        in ``dataset_types``.
+
         Parameters
         ----------
         *dataset_types : `DatasetType`