Increase documentation of ParameterVector and `ParameterVectorEleme…

…nt` (#13761)

These were somewhat lacking before, despite being fairly heavily used.
`ParameterVectorElement` was not publicly documented, despite adding
additional properties that were intended for public use.

(cherry picked from commit d03a61e)

qiskit/circuit/__init__.py

@@ -294,6 +294,7 @@
 * :class:`Parameter`, the atom of compile-time expressions
 * :class:`ParameterExpression`, a symbolic calculation on parameters
 * :class:`ParameterVector`, a convenience collection of many :class:`Parameter`\ s
+* :class:`ParameterVectorElement`, a subclass of :class:`Parameter` used by :class:`ParameterVector`
 
 The :mod:`qiskit.circuit` module also exposes some calculation classes that work with circuits to
 assist compilation workflows.  These include:
@@ -667,12 +668,14 @@
 
 You may want to use many parameters that are related to each other.  To make this easier (and to
 avoid you needing to come up with many names), you can use the convenience constructor
-:class:`ParameterVector`.  The elements of the vector are all valid :class:`Parameter` instances.
+:class:`ParameterVector`.  The elements of the vector are all valid :class:`Parameter` instances, of
+a special subclass :class:`ParameterVectorElement`.
 
 .. autosummary::
     :toctree: ../stubs/
 
     ParameterVector
+    ParameterVectorElement
 
 .. _circuit-control-flow-repr:
 
@@ -1289,7 +1292,7 @@ def __array__(self, dtype=None, copy=None):
 from .reset import Reset
 from .store import Store
 from .parameter import Parameter
-from .parametervector import ParameterVector
+from .parametervector import ParameterVector, ParameterVectorElement
 from .parameterexpression import ParameterExpression
 from .quantumcircuitdata import CircuitInstruction
 from .equivalence import EquivalenceLibrary

qiskit/circuit/parametervector.py

@@ -18,7 +18,12 @@
 
 
 class ParameterVectorElement(Parameter):
-    """An element of a ParameterVector."""
+    """An element of a :class:`ParameterVector`.
+
+    .. note::
+        There is very little reason to ever construct this class directly.  Objects of this type are
+        automatically constructed efficiently as part of creating a :class:`ParameterVector`.
+    """
 
     ___slots__ = ("_vector", "_index")
 
@@ -48,7 +53,18 @@ def __setstate__(self, state):
 
 
 class ParameterVector:
-    """ParameterVector class to quickly generate lists of parameters."""
+    """A container of many related :class:`Parameter` objects.
+
+    This class is faster to construct than constructing many :class:`Parameter` objects
+    individually, and the individual names of the parameters will all share a common stem (the name
+    of the vector).  For a vector called ``v`` with length 3, the individual elements will have
+    names ``v[0]``, ``v[1]`` and ``v[2]``.
+
+    The elements of a vector are sorted by the name of the vector, then the numeric value of their
+    index.
+
+    This class fulfill the :class:`collections.abc.Sequence` interface.
+    """
 
     __slots__ = ("_name", "_params", "_root_uuid")
 
@@ -62,16 +78,20 @@ def __init__(self, name, length=0):
 
     @property
     def name(self):
-        """Returns the name of the ParameterVector."""
+        """The name of the :class:`ParameterVector`."""
         return self._name
 
     @property
     def params(self):
-        """Returns the list of parameters in the ParameterVector."""
+        """A list of the contained :class:`ParameterVectorElement` instances.
+
+        It is not safe to mutate this list."""
         return self._params
 
     def index(self, value):
-        """Returns first index of value."""
+        """Find the index of a :class:`ParameterVectorElement` within the list.
+
+        It is typically much faster to use the :attr:`ParameterVectorElement.index` property."""
         return self._params.index(value)
 
     def __getitem__(self, key):