Expand docstrings for annotated flag on control() and inverse() (#11749)

* Add annotated

* Add returns

* Co-authored-by: Matthew Treinish <mtreinish@kortar.org>

Apply suggestions from Matt's code review

Co-authored-by: Matthew Treinish <mtreinish@kortar.org>

* Format suggestions

* Fix lint

* Apply last round of suggestions

Co-authored-by: Matthew Treinish <mtreinish@kortar.org>

---------

Co-authored-by: Matthew Treinish <mtreinish@kortar.org>

Author: ElePT

qiskit/circuit/library/generalized_gates/unitary.py

@@ -74,7 +74,7 @@ def __init__(
 
         Args:
             data: Unitary operator.
-            label: Unitary name for backend [Default: None].
+            label: Unitary name for backend [Default: ``None``].
             check_input: If set to ``False`` this asserts the input
                 is known to be unitary and the checking to validate this will
                 be skipped. This should only ever be used if you know the

qiskit/circuit/library/hamiltonian_gate.py

@@ -52,7 +52,7 @@ def __init__(
         Args:
             data: A hermitian operator.
             time: Time evolution parameter.
-            label: Unitary name for backend [Default: None].
+            label: Unitary name for backend [Default: ``None``].
 
         Raises:
             ValueError: if input data is not an N-qubit unitary operator.

qiskit/circuit/library/standard_gates/ecr.py

@@ -110,7 +110,17 @@ def _define(self):
         self.definition = qc
 
     def inverse(self, annotated: bool = False):
-        """Return inverse ECR gate (itself)."""
+        """Return inverse ECR gate (itself).
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as this gate
+                is self-inverse.
+
+        Returns:
+            ECRGate: inverse gate (self-inverse).
+        """
         return ECRGate()  # self-inverse
 
     def __eq__(self, other):

qiskit/circuit/library/standard_gates/global_phase.py

@@ -53,9 +53,19 @@ def _define(self):
         self.definition = qc
 
     def inverse(self, annotated: bool = False):
-        r"""Return inverted GlobalPhaseGate gate.
+        r"""Return inverse GlobalPhaseGate gate.
 
         :math:`\text{GlobalPhaseGate}(\lambda)^{\dagger} = \text{GlobalPhaseGate}(-\lambda)`
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as the inverse
+                is always another :class:`.GlobalPhaseGate` with an inverted
+                parameter value.
+
+        Returns:
+            GlobalPhaseGate: inverse gate.
         """
         return GlobalPhaseGate(-self.params[0])
 

qiskit/circuit/library/standard_gates/h.py

@@ -85,10 +85,10 @@ def control(
         One control qubit returns a CH gate.
 
         Args:
-            num_ctrl_qubits (int): number of control qubits.
-            label (str or None): An optional label for the gate [Default: None]
-            ctrl_state (int or str or None): control state expressed as integer,
-                string (e.g. '110'), or None. If None, use all 1s.
+            num_ctrl_qubits: number of control qubits.
+            label: An optional label for the gate [Default: ``None``]
+            ctrl_state: control state expressed as integer,
+                string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
             annotated: indicates whether the controlled gate can be implemented
                 as an annotated gate.
 
@@ -107,7 +107,17 @@ def control(
         return gate
 
     def inverse(self, annotated: bool = False):
-        r"""Return inverted H gate (itself)."""
+        r"""Return inverted H gate (itself).
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as this gate
+                is self-inverse.
+
+        Returns:
+            HGate: inverse gate (self-inverse).
+        """
         return HGate()  # self-inverse
 
     def __eq__(self, other):

qiskit/circuit/library/standard_gates/i.py

@@ -52,7 +52,17 @@ def __init__(self, label: Optional[str] = None, *, duration=None, unit="dt"):
     _singleton_lookup_key = stdlib_singleton_key()
 
     def inverse(self, annotated: bool = False):
-        """Invert this gate."""
+        """Returne the inverse gate (itself).
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as this gate
+                is self-inverse.
+
+        Returns:
+            IGate: inverse gate (self-inverse).
+        ."""
         return IGate()  # self-inverse
 
     def power(self, exponent: float):

qiskit/circuit/library/standard_gates/p.py

@@ -101,10 +101,10 @@ def control(
         """Return a (multi-)controlled-Phase gate.
 
         Args:
-            num_ctrl_qubits (int): number of control qubits.
-            label (str or None): An optional label for the gate [Default: None]
-            ctrl_state (int or str or None): control state expressed as integer,
-                string (e.g. '110'), or None. If None, use all 1s.
+            num_ctrl_qubits: number of control qubits.
+            label: An optional label for the gate [Default: ``None``]
+            ctrl_state: control state expressed as integer,
+                string (e.g. ``'110'``), or ``None``. If ``None``, use all 1s.
             annotated: indicates whether the controlled gate can be implemented
                 as an annotated gate.
 
@@ -127,7 +127,17 @@ def control(
         return gate
 
     def inverse(self, annotated: bool = False):
-        r"""Return inverted Phase gate (:math:`Phase(\lambda)^{\dagger} = Phase(-\lambda)`)"""
+        r"""Return inverted Phase gate (:math:`Phase(\lambda)^{\dagger} = Phase(-\lambda)`)
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as the inverse
+                of this gate is always another :class:`.PGate` with an inverse parameter value.
+
+        Returns:
+            PGate: inverse gate.
+        """
         return PhaseGate(-self.params[0])
 
     def __array__(self, dtype=None):
@@ -244,10 +254,10 @@ def control(
         """Controlled version of this gate.
 
         Args:
-            num_ctrl_qubits (int): number of control qubits.
-            label (str or None): An optional label for the gate [Default: None]
-            ctrl_state (int or str or None): control state expressed as integer,
-                string (e.g. '110'), or None. If None, use all 1s.
+            num_ctrl_qubits: number of control qubits.
+            label: An optional label for the gate [Default: ``None``]
+            ctrl_state: control state expressed as integer,
+                string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
             annotated: indicates whether the controlled gate can be implemented
                 as an annotated gate.
 
@@ -370,10 +380,10 @@ def control(
         """Controlled version of this gate.
 
         Args:
-            num_ctrl_qubits (int): number of control qubits.
-            label (str or None): An optional label for the gate [Default: None]
-            ctrl_state (int or str or None): control state expressed as integer,
-                string (e.g. '110'), or None. If None, use all 1s.
+            num_ctrl_qubits: number of control qubits.
+            label: An optional label for the gate [Default: ``None``]
+            ctrl_state: control state expressed as integer,
+                string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
             annotated: indicates whether the controlled gate can be implemented
                 as an annotated gate.
 

qiskit/circuit/library/standard_gates/r.py

@@ -80,9 +80,16 @@ def _define(self):
         self.definition = qc
 
     def inverse(self, annotated: bool = False):
-        """Invert this gate.
+        """Invert this gate as: :math:`r(θ, φ)^dagger = r(-θ, φ)`
 
-        r(θ, φ)^dagger = r(-θ, φ)
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as the inverse
+                of this gate is always a :class:`.RGate` with an inverted parameter value.
+
+        Returns:
+            RGate: inverse gate.
         """
         return RGate(-self.params[0], self.params[1])
 

qiskit/circuit/library/standard_gates/rx.py

@@ -82,10 +82,10 @@ def control(
         """Return a (multi-)controlled-RX gate.
 
         Args:
-            num_ctrl_qubits (int): number of control qubits.
-            label (str or None): An optional label for the gate [Default: None]
-            ctrl_state (int or str or None): control state expressed as integer,
-                string (e.g. '110'), or None. If None, use all 1s.
+            num_ctrl_qubits: number of control qubits.
+            label: An optional label for the gate [Default: ``None``]
+            ctrl_state: control state expressed as integer,
+                string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
             annotated: indicates whether the controlled gate can be implemented
                 as an annotated gate.
 
@@ -108,6 +108,15 @@ def inverse(self, annotated: bool = False):
         r"""Return inverted RX gate.
 
         :math:`RX(\lambda)^{\dagger} = RX(-\lambda)`
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as the inverse
+                of this gate is always a :class:`.RXGate` with an inverted parameter value.
+
+        Returns:
+            RXGate: inverse gate.
         """
         return RXGate(-self.params[0])
 
@@ -242,7 +251,17 @@ def _define(self):
         self.definition = qc
 
     def inverse(self, annotated: bool = False):
-        """Return inverse CRX gate (i.e. with the negative rotation angle)."""
+        """Return inverse CRX gate (i.e. with the negative rotation angle).
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as the inverse
+                of this gate is always a :class:`.CRXGate` with an inverted parameter value.
+
+        Returns:
+            CRXGate: inverse gate.
+        """
         return CRXGate(-self.params[0], ctrl_state=self.ctrl_state)
 
     def __array__(self, dtype=None):

qiskit/circuit/library/standard_gates/rxx.py

@@ -109,7 +109,17 @@ def _define(self):
         self.definition = qc
 
     def inverse(self, annotated: bool = False):
-        """Return inverse RXX gate (i.e. with the negative rotation angle)."""
+        """Return inverse RXX gate (i.e. with the negative rotation angle).
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as the inverse
+                of this gate is always a :class:`.RXXGate` with an inverted parameter value.
+
+        Returns:
+            RXXGate: inverse gate.
+        """
         return RXXGate(-self.params[0])
 
     def __array__(self, dtype=None):

qiskit/circuit/library/standard_gates/ry.py

@@ -81,10 +81,10 @@ def control(
         """Return a (multi-)controlled-RY gate.
 
         Args:
-            num_ctrl_qubits (int): number of control qubits.
-            label (str or None): An optional label for the gate [Default: None]
-            ctrl_state (int or str or None): control state expressed as integer,
-                string (e.g. '110'), or None. If None, use all 1s.
+            num_ctrl_qubits: number of control qubits.
+            label: An optional label for the gate [Default: ``None``]
+            ctrl_state: control state expressed as integer,
+                string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
             annotated: indicates whether the controlled gate can be implemented
                 as an annotated gate.
 
@@ -104,9 +104,18 @@ def control(
         return gate
 
     def inverse(self, annotated: bool = False):
-        r"""Return inverted RY gate.
+        r"""Return inverse RY gate.
 
         :math:`RY(\lambda)^{\dagger} = RY(-\lambda)`
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as the inverse
+                of this gate is always a :class:`.RYGate` with an inverted parameter value.
+
+        Returns:
+            RYGate: inverse gate.
         """
         return RYGate(-self.params[0])
 
@@ -237,7 +246,17 @@ def _define(self):
         self.definition = qc
 
     def inverse(self, annotated: bool = False):
-        """Return inverse CRY gate (i.e. with the negative rotation angle)."""
+        """Return inverse CRY gate (i.e. with the negative rotation angle)
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as the inverse
+                of this gate is always a :class:`.CRYGate` with an inverted parameter value.
+
+        Returns:
+            CRYGate: inverse gate.
+        ."""
         return CRYGate(-self.params[0], ctrl_state=self.ctrl_state)
 
     def __array__(self, dtype=None):

qiskit/circuit/library/standard_gates/ryy.py

@@ -109,7 +109,17 @@ def _define(self):
         self.definition = qc
 
     def inverse(self, annotated: bool = False):
-        """Return inverse RYY gate (i.e. with the negative rotation angle)."""
+        """Return inverse RYY gate (i.e. with the negative rotation angle).
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as the inverse
+                of this gate is always a :class:`.RYYGate` with an inverted parameter value.
+
+        Returns:
+            RYYGate: inverse gate.
+        """
         return RYYGate(-self.params[0])
 
     def __array__(self, dtype=None):

qiskit/circuit/library/standard_gates/rz.py

@@ -92,10 +92,10 @@ def control(
         """Return a (multi-)controlled-RZ gate.
 
         Args:
-            num_ctrl_qubits (int): number of control qubits.
-            label (str or None): An optional label for the gate [Default: None]
-            ctrl_state (int or str or None): control state expressed as integer,
-                string (e.g. '110'), or None. If None, use all 1s.
+            num_ctrl_qubits: number of control qubits.
+            label: An optional label for the gate [Default: ``None``]
+            ctrl_state: control state expressed as integer,
+                string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
             annotated: indicates whether the controlled gate can be implemented
                 as an annotated gate.
 
@@ -118,6 +118,15 @@ def inverse(self, annotated: bool = False):
         r"""Return inverted RZ gate
 
         :math:`RZ(\lambda)^{\dagger} = RZ(-\lambda)`
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as the inverse
+                of this gate is always a :class:`.RZGate` with an inverted parameter value.
+
+        Returns:
+            RZGate: inverse gate.
         """
         return RZGate(-self.params[0])
 
@@ -255,7 +264,17 @@ def _define(self):
         self.definition = qc
 
     def inverse(self, annotated: bool = False):
-        """Return inverse CRZ gate (i.e. with the negative rotation angle)."""
+        """Return inverse CRZ gate (i.e. with the negative rotation angle).
+
+        Args:
+            annotated: when set to ``True``, this is typically used to return an
+                :class:`.AnnotatedOperation` with an inverse modifier set instead of a concrete
+                :class:`.Gate`. However, for this class this argument is ignored as the inverse
+                of this gate is always a :class:`.CRZGate` with an inverted parameter value.
+
+         Returns:
+            CRZGate: inverse gate.
+        """
         return CRZGate(-self.params[0], ctrl_state=self.ctrl_state)
 
     def __array__(self, dtype=None):