From d03a61e0970d2d7cb90ee80853273f989e16de3b Mon Sep 17 00:00:00 2001
From: Jake Lishman <jake.lishman@ibm.com>
Date: Fri, 31 Jan 2025 10:55:29 +0000
Subject: [PATCH] Increase documentation of `ParameterVector` and
 `ParameterVectorElement` (#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.
---
 qiskit/circuit/__init__.py        |  7 +++++--
 qiskit/circuit/parametervector.py | 30 +++++++++++++++++++++++++-----
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/qiskit/circuit/__init__.py b/qiskit/circuit/__init__.py
index 8c331d1563f3..42cb8ddb83d1 100644
--- a/qiskit/circuit/__init__.py
+++ b/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:
@@ -671,12 +672,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:
 
@@ -1298,7 +1301,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
diff --git a/qiskit/circuit/parametervector.py b/qiskit/circuit/parametervector.py
index 7b32395e1430..d77e0a221bad 100644
--- a/qiskit/circuit/parametervector.py
+++ b/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):