Improve common_gates docstrings (quantumlib#5722)

Bundle of minor fixes for docstrings in `common_gates.py`.

Author: 95-martin-orion

cirq-core/cirq/ops/common_gates.py

@@ -197,13 +197,14 @@ def controlled(
         this is possible.
 
         The conditions for the override to occur are:
-            * The `global_shift` of the `XPowGate` is 0.
-            * The `control_values` and `control_qid_shape` are compatible with
-                the `CXPowGate`:
-                * The last value of `control_qid_shape` is a qubit.
-                * The last value of `control_values` corresponds to the
-                    control being satisfied if that last qubit is 1 and
-                    not satisfied if the last qubit is 0.
+
+        * The `global_shift` of the `XPowGate` is 0.
+        * The `control_values` and `control_qid_shape` are compatible with
+            the `CXPowGate`:
+            * The last value of `control_qid_shape` is a qubit.
+            * The last value of `control_values` corresponds to the
+                control being satisfied if that last qubit is 1 and
+                not satisfied if the last qubit is 0.
 
         If these conditions are met, then the returned object is a `CXPowGate`
         or, in the case that there is more than one controlled qudit, a
@@ -215,6 +216,22 @@ def controlled(
 
         If the above conditions are not met, a `ControlledGate` of this
         gate will be returned.
+
+        Args:
+            num_controls: Total number of control qubits.
+            control_values: Which control computational basis state to apply the
+                sub gate.  A sequence of length `num_controls` where each
+                entry is an integer (or set of integers) corresponding to the
+                computational basis state (or set of possible values) where that
+                control is enabled.  When all controls are enabled, the sub gate is
+                applied.  If unspecified, control values default to 1.
+            control_qid_shape: The qid shape of the controls.  A tuple of the
+                expected dimension of each control qid.  Defaults to
+                `(2,) * num_controls`.  Specify this argument when using qudits.
+
+        Returns:
+            A `cirq.ControlledGate` (or `cirq.CXPowGate` if possible) representing
+                `self` controlled by the given control values and qubits.
         """
         result = super().controlled(num_controls, control_values, control_qid_shape)
         if (
@@ -309,6 +326,11 @@ class Rx(XPowGate):
     """
 
     def __init__(self, *, rads: value.TParamVal):
+        """Initialize an Rx (`cirq.XPowGate`).
+
+        Args:
+            rads: Radians to rotate about the X axis of the Bloch sphere.
+        """
         self._rads = rads
         super().__init__(exponent=rads / _pi(rads), global_shift=-0.5)
 
@@ -478,6 +500,11 @@ class Ry(YPowGate):
     """
 
     def __init__(self, *, rads: value.TParamVal):
+        """Initialize an Ry (`cirq.YPowGate`).
+
+        Args:
+            rads: Radians to rotate about the Y axis of the Bloch sphere.
+        """
         self._rads = rads
         super().__init__(exponent=rads / _pi(rads), global_shift=-0.5)
 
@@ -617,13 +644,14 @@ def controlled(
         this is possible.
 
         The conditions for the override to occur are:
-            * The `global_shift` of the `ZPowGate` is 0.
-            * The `control_values` and `control_qid_shape` are compatible with
-                the `CZPowGate`:
-                * The last value of `control_qid_shape` is a qubit.
-                * The last value of `control_values` corresponds to the
-                    control being satisfied if that last qubit is 1 and
-                    not satisfied if the last qubit is 0.
+
+        * The `global_shift` of the `ZPowGate` is 0.
+        * The `control_values` and `control_qid_shape` are compatible with
+            the `CZPowGate`:
+            * The last value of `control_qid_shape` is a qubit.
+            * The last value of `control_values` corresponds to the
+                control being satisfied if that last qubit is 1 and
+                not satisfied if the last qubit is 0.
 
         If these conditions are met, then the returned object is a `CZPowGate`
         or, in the case that there is more than one controlled qudit, a
@@ -635,6 +663,22 @@ def controlled(
 
         If the above conditions are not met, a `ControlledGate` of this
         gate will be returned.
+
+        Args:
+            num_controls: Total number of control qubits.
+            control_values: Which control computational basis state to apply the
+                sub gate.  A sequence of length `num_controls` where each
+                entry is an integer (or set of integers) corresponding to the
+                computational basis state (or set of possible values) where that
+                control is enabled.  When all controls are enabled, the sub gate is
+                applied.  If unspecified, control values default to 1.
+            control_qid_shape: The qid shape of the controls.  A tuple of the
+                expected dimension of each control qid.  Defaults to
+                `(2,) * num_controls`.  Specify this argument when using qudits.
+
+        Returns:
+            A `cirq.ControlledGate` (or `cirq.CZPowGate` if possible) representing
+                `self` controlled by the given control values and qubits.
         """
         result = super().controlled(num_controls, control_values, control_qid_shape)
         if (
@@ -783,6 +827,11 @@ class Rz(ZPowGate):
     """
 
     def __init__(self, *, rads: value.TParamVal):
+        """Initialize an Rz (`cirq.ZPowGate`).
+
+        Args:
+            rads: Radians to rotate about the Z axis of the Bloch sphere.
+        """
         self._rads = rads
         super().__init__(exponent=rads / _pi(rads), global_shift=-0.5)
 
@@ -1031,13 +1080,14 @@ def controlled(
         this is possible.
 
         The conditions for the override to occur are:
-            * The `global_shift` of the `CZPowGate` is 0.
-            * The `control_values` and `control_qid_shape` are compatible with
-                the `CCZPowGate`:
-                * The last value of `control_qid_shape` is a qubit.
-                * The last value of `control_values` corresponds to the
-                    control being satisfied if that last qubit is 1 and
-                    not satisfied if the last qubit is 0.
+
+        * The `global_shift` of the `CZPowGate` is 0.
+        * The `control_values` and `control_qid_shape` are compatible with
+            the `CCZPowGate`:
+            * The last value of `control_qid_shape` is a qubit.
+            * The last value of `control_values` corresponds to the
+                control being satisfied if that last qubit is 1 and
+                not satisfied if the last qubit is 0.
 
         If these conditions are met, then the returned object is a `CCZPowGate`
         or, in the case that there is more than one controlled qudit, a
@@ -1049,6 +1099,22 @@ def controlled(
 
         If the above conditions are not met, a `ControlledGate` of this
         gate will be returned.
+
+        Args:
+            num_controls: Total number of control qubits.
+            control_values: Which control computational basis state to apply the
+                sub gate.  A sequence of length `num_controls` where each
+                entry is an integer (or set of integers) corresponding to the
+                computational basis state (or set of possible values) where that
+                control is enabled.  When all controls are enabled, the sub gate is
+                applied.  If unspecified, control values default to 1.
+            control_qid_shape: The qid shape of the controls.  A tuple of the
+                expected dimension of each control qid.  Defaults to
+                `(2,) * num_controls`.  Specify this argument when using qudits.
+
+        Returns:
+            A `cirq.ControlledGate` (or `cirq.CCZPowGate` if possible) representing
+                `self` controlled by the given control values and qubits.
         """
         result = super().controlled(num_controls, control_values, control_qid_shape)
         if (
@@ -1213,13 +1279,14 @@ def controlled(
         this is possible.
 
         The conditions for the override to occur are:
-            * The `global_shift` of the `CXPowGate` is 0.
-            * The `control_values` and `control_qid_shape` are compatible with
-                the `CCXPowGate`:
-                * The last value of `control_qid_shape` is a qubit.
-                * The last value of `control_values` corresponds to the
-                    control being satisfied if that last qubit is 1 and
-                    not satisfied if the last qubit is 0.
+
+        * The `global_shift` of the `CXPowGate` is 0.
+        * The `control_values` and `control_qid_shape` are compatible with
+            the `CCXPowGate`:
+            * The last value of `control_qid_shape` is a qubit.
+            * The last value of `control_values` corresponds to the
+                control being satisfied if that last qubit is 1 and
+                not satisfied if the last qubit is 0.
 
         If these conditions are met, then the returned object is a `CCXPowGate`
         or, in the case that there is more than one controlled qudit, a
@@ -1231,6 +1298,22 @@ def controlled(
 
         If the above conditions are not met, a `ControlledGate` of this
         gate will be returned.
+
+        Args:
+            num_controls: Total number of control qubits.
+            control_values: Which control computational basis state to apply the
+                sub gate.  A sequence of length `num_controls` where each
+                entry is an integer (or set of integers) corresponding to the
+                computational basis state (or set of possible values) where that
+                control is enabled.  When all controls are enabled, the sub gate is
+                applied.  If unspecified, control values default to 1.
+            control_qid_shape: The qid shape of the controls.  A tuple of the
+                expected dimension of each control qid.  Defaults to
+                `(2,) * num_controls`.  Specify this argument when using qudits.
+
+        Returns:
+            A `cirq.ControlledGate` (or `cirq.CCXPowGate` if possible) representing
+                `self` controlled by the given control values and qubits.
         """
         result = super().controlled(num_controls, control_values, control_qid_shape)
         if (

cirq-core/cirq/ops/raw_types.py

@@ -367,7 +367,6 @@ def controlled(
         """Returns a controlled version of this gate. If no arguments are
         specified, defaults to a single qubit control.
 
-
         Args:
             num_controls: Total number of control qubits.
             control_values: Which control computational basis state to apply the
@@ -379,6 +378,11 @@ def controlled(
             control_qid_shape: The qid shape of the controls.  A tuple of the
                 expected dimension of each control qid.  Defaults to
                 `(2,) * num_controls`.  Specify this argument when using qudits.
+
+        Returns:
+            A `cirq.Gate` representing `self` controlled by the given control values
+                and qubits. This is a `cirq.ControlledGate` in the base
+                implementation, but subclasses may return a different gate type.
         """
 
         if num_controls == 0: