Update docs with @JoelPasvolsky review suggestions

Author: randomir

dimod/core/composite.py

@@ -54,17 +54,18 @@
 
 
 class Composite(Scoped):
-    """Abstract base class for dimod composites over scoped resources.
+    """Abstract base class for dimod composites.
 
     Provides the :attr:`Composite.child` mixin property and defines the :attr:`Composite.children`
     abstract property to be implemented. These define the supported samplers for the composed sampler.
 
-    It also implements default :meth:`.close` operation that closes all child samplers.
+    :class:`.Composite` implements the :class:`~dimod.core.scoped.Scoped` interface, and
+    provides :meth:`.close` method that closes all child samplers or composites.
 
     .. versionchanged:: 0.12.19
-        :class:`.Composite` now implements the :class:`~dimod.core.scoped.Scoped`
-        interface, meaning all composites support context manager protocol and
-        release scope-based resources of sub-samplers/composites by default.
+        Implemented the :class:`~dimod.core.scoped.Scoped` interface. Now all
+        composites support context manager protocol and release scope-based
+        resources of sub-samplers/composites by default.
     """
 
     @abc.abstractproperty
@@ -83,17 +84,16 @@ def child(self):
             raise RuntimeError("A Composite must have at least one child Sampler")
 
     def close(self):
-        """Release resources of child samplers/composites, in case they allocated
-        any scope-bound resources.
+        """Release any scope-bound resources of child samplers or composites.
 
         .. note::
             If a :class:`.Composite` subclass doesn't allocate resources that have
-            to be explicitly released, there's not need to override the default
+            to be explicitly released, there's no need to override the default
             :meth:`~.Composite.close` implementation.
 
-            However, if you do implement it on a subclass, make sure to either
-            call ``super().close()``, or to explicitly close all child
-            samplers/composites.
+            However, if you do implement :meth:`~.Composite.close` on a subclass,
+            make sure to either call ``super().close()``, or to explicitly close
+            all child samplers/composites.
 
         .. versionadded:: 0.12.19
             :class:`.Composite` now implements the :class:`~dimod.core.scoped.Scoped`

dimod/core/sampler.py

@@ -174,8 +174,9 @@ class Sampler(Scoped, metaclass=SamplerABCMeta):
     Also includes utility method :meth:`~.Sampler.remove_unknown_kwargs`,
     which may be used in sample methods to handle unknown kwargs.
 
-    Default implementation of :meth:`~.Sampler.close` does nothing, so it should
-    be overridden to release scope-based sampler resources, it any.
+    :class:`.Sampler` implements the :class:`~dimod.core.scoped.Scoped` interface,
+    but the default implementation of :meth:`~.Sampler.close` does nothing. It
+    should be overridden to release any scope-based sampler resources.
 
     .. versionchanged:: 0.12.19
         :class:`.Sampler` now implements the :class:`~dimod.core.scoped.Scoped`

docs/reference/sampler_composites/api.rst

@@ -22,44 +22,51 @@ ABCs.
         - Abstract Properties
         - Abstract Methods
         - Mixin Methods
-    *   - :class:`.Sampler`
+    *   - :class:`.Scoped`
+        -
         -
+        - :meth:`~.Scoped.close`
+        - :meth:`~.Scoped.__enter__`, :meth:`~.Scoped.__exit__`
+    *   - :class:`.Sampler`
+        - :class:`.Scoped`
         - :attr:`~.Sampler.parameters`, :attr:`~.Sampler.properties`
         - at least one of
           :meth:`~.Sampler.sample`, :meth:`~.Sampler.sample_ising`, :meth:`~.Sampler.sample_qubo`
-        - :meth:`~.Sampler.sample`, :meth:`~.Sampler.sample_ising`, :meth:`~.Sampler.sample_qubo`
+        - :meth:`~.Sampler.sample`, :meth:`~.Sampler.sample_ising`, :meth:`~.Sampler.sample_qubo`,
+          :meth:`~.Sampler.close`
     *   - :class:`.Structured`
         -
         - :attr:`~.Structured.nodelist`, :attr:`~.Structured.edgelist`
         -
         - :attr:`~.Structured.structure`, :attr:`~.Structured.adjacency`, :meth:`~.Structured.to_networkx_graph`
     *   - :class:`.Composite`
-        -
+        - :class:`.Scoped`
         - :attr:`~.Composite.children`
         -
-        - :attr:`~.Composite.child`
+        - :attr:`~.Composite.child`, :meth:`~.Composite.close`
     *   - :class:`.ComposedSampler`
         - :class:`.Sampler`, :class:`.Composite`
         - :attr:`~.Sampler.parameters`, :attr:`~.Sampler.properties`, :attr:`~.Composite.children`
         - at least one of
           :meth:`~.Sampler.sample`, :meth:`~.Sampler.sample_ising`, :meth:`~.Sampler.sample_qubo`
         - :meth:`~.Sampler.sample`, :meth:`~.Sampler.sample_ising`, :meth:`~.Sampler.sample_qubo`,
-          :attr:`~.Composite.child`
+          :attr:`~.Composite.child`, :meth:`~.Composite.close`
     *   - :class:`.Initialized`
         -
         -
         -
         - :attr:`~.Initialized.parse_initial_states`
     *   - :class:`.PolySampler`
-        -
+        - :class:`.Scoped`
         - :attr:`~.PolySampler.parameters`, :attr:`~.PolySampler.properties`
         - :meth:`~.PolySampler.sample_poly`
-        - :meth:`~.PolySampler.sample_hising`, :meth:`~.PolySampler.sample_hubo`
+        - :meth:`~.PolySampler.sample_hising`, :meth:`~.PolySampler.sample_hubo`, :meth:`~.PolySampler.close`
     *   - :class:`.ComposedPolySampler`
         - :class:`.PolySampler`, :class:`.Composite`
         - :attr:`~.PolySampler.parameters`, :attr:`~.PolySampler.properties`, :attr:`~.Composite.children`
         - :meth:`~.Sampler.sample_poly`
-        - :meth:`~.Sampler.sample_hising`, :meth:`~.Sampler.sample_hubo`, :attr:`~.Composite.child`
+        - :meth:`~.Sampler.sample_hising`, :meth:`~.Sampler.sample_hubo`, :attr:`~.Composite.child`,
+          :meth:`~.PolySampler.close`
 
 The table shows, for example, that the :class:`.Sampler` class requires that you implement
 the :attr:`~.Sampler.parameters` and :attr:`~.Sampler.properties` properties and at least