Removing more documentation lint (#4679)

Getting closer!

cirq-core/cirq/contrib/graph_device/graph_device.py

@@ -120,8 +120,6 @@ class UndirectedGraphDevice(devices.Device):
         * duration_of does not check that operation is valid.
     """
 
-    # TODO(#3388) Add documentation for Raises.
-    # pylint: disable=missing-raises-doc
     def __init__(
         self,
         device_graph: Optional[UndirectedHypergraph] = None,
@@ -136,6 +134,9 @@ def __init__(
             crosstalk_graph: An undirected hypergraph whose vertices are edges
                 of device_graph and whose edges give simultaneity constraints
                 thereon.
+
+        Raises:
+            TypeError: If the crosstalk graph is not a valid crosstalk graph.
         """
 
         if device_graph is None:
@@ -150,7 +151,6 @@ def __init__(
         self.device_graph = device_graph
         self.crosstalk_graph = crosstalk_graph
 
-    # pylint: enable=missing-raises-doc
     @property
     def qubits(self) -> Tuple['cirq.Qid', ...]:
         return cast(Tuple['cirq.Qid', ...], tuple(sorted(self.device_graph.vertices)))

cirq-core/cirq/contrib/quimb/density_matrix.py

@@ -75,8 +75,6 @@ def _add_to_positions(
     positions[(f'i{mi}b', _qpos_tag(qubits))] = (mi * x_scale, y_scale * qy + yb_offset)
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def circuit_to_density_matrix_tensors(
     circuit: cirq.Circuit, qubits: Optional[Sequence[cirq.Qid]] = None
 ) -> Tuple[List[qtn.Tensor], Dict['cirq.Qid', int], Dict[Tuple[str, str], Tuple[float, float]]]:
@@ -103,6 +101,9 @@ def circuit_to_density_matrix_tensors(
         positions: A positions dictionary suitable for passing to tn.graph()'s
             `fix` argument to draw the resulting tensor network similar to a
             quantum circuit.
+
+    Raises:
+        ValueError: If an op is encountered that cannot be converted.
     """
     if qubits is None:
         # coverage: ignore
@@ -195,7 +196,6 @@ def _positions(_mi, _these_qubits):
     return tensors, qubit_frontier, positions
 
 
-# pylint: enable=missing-raises-doc
 def tensor_density_matrix(
     circuit: cirq.Circuit, qubits: Optional[List[cirq.Qid]] = None
 ) -> np.ndarray:

cirq-core/cirq/experiments/google_v2_supremacy_circuit.py

@@ -176,12 +176,11 @@ def _add_cz_layer(layer_index: int, circuit: circuits.Circuit) -> int:
     return layer_index
 
 
-# TODO(#3388) Add summary line to docstring.
-# pylint: disable=docstring-first-line-empty
 def _make_cz_layer(
     qubits: Iterable[devices.GridQubit], layer_index: int
 ) -> Iterable[ops.Operation]:
-    """
+    """Make the CZ layer gate.
+
     Each layer index corresponds to a shift/transpose of this CZ pattern:
 
         ●───●   ●   ●   ●───●   ●   ● . . .
@@ -235,6 +234,3 @@ def _make_cz_layer(
             continue  # No CZ along this edge for this layer.
 
         yield ops.common_gates.CZ(q, q2)
-
-
-# pylint: enable=docstring-first-line-empty

cirq-core/cirq/experiments/t1_decay_experiment.py

@@ -31,8 +31,6 @@
 optimize = _import.LazyLoader("optimize", globals(), "scipy.optimize")
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def t1_decay(
     sampler: 'cirq.Sampler',
     *,
@@ -58,6 +56,10 @@ def t1_decay(
 
     Returns:
         A T1DecayResult object that stores and can plot the data.
+
+    Raises:
+        ValueError: If the supplied parameters are not valid: negative repetitions,
+            max delay less than min, or min delay less than 0.
     """
     min_delay_dur = value.Duration(min_delay)
     max_delay_dur = value.Duration(max_delay)
@@ -96,7 +98,6 @@ def t1_decay(
     return T1DecayResult(tab)
 
 
-# pylint: enable=missing-raises-doc
 class T1DecayResult:
     """Results from a Rabi oscillation experiment."""
 

cirq-core/cirq/linalg/decompositions.py

@@ -876,8 +876,6 @@ def kak_decomposition(
     )
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def kak_vector(
     unitary: Union[Iterable[np.ndarray], np.ndarray],
     *,
@@ -930,6 +928,9 @@ def kak_vector(
         the same as the input shape, except the two unitary matrix axes are
         replaced by the kak vector axis (i.e. the output has shape
         `unitary.shape[:-2] + (3,)`).
+
+    Raises:
+        ValueError: If `atol` is negative or if the unitary has the wrong shape.
     """
     unitary = np.asarray(unitary)
     if len(unitary) == 0:
@@ -979,7 +980,6 @@ def kak_vector(
     return _canonicalize_kak_vector(k_vec, atol)
 
 
-# pylint: enable=missing-raises-doc
 def _canonicalize_kak_vector(k_vec: np.ndarray, atol: float) -> np.ndarray:
     r"""Map a KAK vector into its Weyl chamber equivalent vector.
 
@@ -1027,9 +1027,6 @@ def _canonicalize_kak_vector(k_vec: np.ndarray, atol: float) -> np.ndarray:
     return k_vec
 
 
-# TODO(#3388) Add documentation for Args.
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-param-doc,missing-raises-doc
 def num_cnots_required(u: np.ndarray, atol: float = 1e-8) -> int:
     """Returns the min number of CNOT/CZ gates required by a two-qubit unitary.
 
@@ -1038,10 +1035,14 @@ def num_cnots_required(u: np.ndarray, atol: float = 1e-8) -> int:
     Controlled-Not Gates”.  https://arxiv.org/abs/quant-ph/0308045
 
     Args:
-        u: a two-qubit unitary
+        u: A two-qubit unitary.
+        atol: The absolute tolerance used to make this judgement.
 
     Returns:
-        the number of CNOT or CZ gates required to implement the unitary
+        The number of CNOT or CZ gates required to implement the unitary.
+
+    Raises:
+        ValueError: If the shape of `u` is not 4 by 4.
     """
     if u.shape != (4, 4):
         raise ValueError(f"Expected unitary of shape (4,4), instead got {u.shape}")
@@ -1061,7 +1062,6 @@ def num_cnots_required(u: np.ndarray, atol: float = 1e-8) -> int:
     return 3
 
 
-# pylint: enable=missing-param-doc,missing-raises-doc
 def _gamma(u: np.ndarray) -> np.ndarray:
     """Gamma function to convert u to the magic basis.
 

cirq-core/cirq/ops/controlled_gate.py

@@ -29,8 +29,6 @@ class ControlledGate(raw_types.Gate):
     This object is typically created via `gate.controlled()`.
     """
 
-    # TODO(#3388) Add documentation for Raises.
-    # pylint: disable=missing-raises-doc
     def __init__(
         self,
         sub_gate: 'cirq.Gate',
@@ -54,6 +52,10 @@ def __init__(
                 expected dimension of each control qid.  Defaults to
                 `(2,) * num_controls`.  Specify this argument when using qudits.
 
+        Raises:
+            ValueError: If the `control_values` or `control_qid_shape` does not
+                match with `num_conrols`, or if the `control_values` are out of
+                bounds.
         """
         if num_controls is None:
             if control_values is not None:
@@ -94,7 +96,6 @@ def __init__(
         else:
             self.sub_gate = sub_gate
 
-    # pylint: enable=missing-raises-doc
     def num_controls(self) -> int:
         return len(self.control_qid_shape)
 

cirq-core/cirq/ops/dense_pauli_string.py

@@ -109,14 +109,13 @@ def _value_equality_values_(self):
         # Would cause approx_eq to false positive when atol > 1.
         return self.coefficient, tuple(PAULI_CHARS[p] for p in self.pauli_mask)
 
-    # TODO(#3388) Add documentation for Args.
-    # pylint: disable=missing-param-doc
     @classmethod
     def one_hot(cls: Type[TCls], *, index: int, length: int, pauli: 'cirq.PAULI_GATE_LIKE') -> TCls:
         """Creates a dense pauli string with only one non-identity Pauli.
 
         Args:
             index: The index of the Pauli that is not an identity.
+            length: The total length of the string to create.
             pauli: The pauli gate to put at the hot index. Can be set to either
                 a string ('X', 'Y', 'Z', 'I'), a cirq gate (`cirq.X`,
                 `cirq.Y`, `cirq.Z`, or `cirq.I`), or an integer (0=I, 1=X, 2=Y,
@@ -127,7 +126,6 @@ def one_hot(cls: Type[TCls], *, index: int, length: int, pauli: 'cirq.PAULI_GATE
         concrete_cls = cast(Callable, DensePauliString if cls is BaseDensePauliString else cls)
         return concrete_cls(pauli_mask=mask)
 
-    # pylint: enable=missing-param-doc
     @classmethod
     def eye(cls: Type[TCls], length: int) -> TCls:
         """Creates a dense pauli string containing only identity gates.
@@ -283,8 +281,6 @@ def __abs__(self):
     def on(self, *qubits) -> 'cirq.PauliString':
         return self.sparse(qubits)
 
-    # TODO(#3388) Add documentation for Raises.
-    # pylint: disable=missing-raises-doc
     def sparse(self, qubits: Optional[Sequence['cirq.Qid']] = None) -> 'cirq.PauliString':
         """A `cirq.PauliString` version of this dense pauli string.
 
@@ -295,6 +291,10 @@ def sparse(self, qubits: Optional[Sequence['cirq.Qid']] = None) -> 'cirq.PauliSt
         Returns:
             A `cirq.PauliString` with the non-identity operations from
             this dense pauli string applied to appropriate qubits.
+
+        Raises:
+            ValueError: If the number of qubits supplied does not match that of
+                this instance.
         """
         if qubits is None:
             from cirq import devices
@@ -309,7 +309,6 @@ def sparse(self, qubits: Optional[Sequence['cirq.Qid']] = None) -> 'cirq.PauliSt
             qubit_pauli_map={q: PAULI_GATES[p] for q, p in zip(qubits, self.pauli_mask) if p},
         )
 
-    # pylint: enable=missing-raises-doc
     def __str__(self) -> str:
         if self.coefficient == 1:
             coef = '+'

cirq-core/cirq/ops/pauli_gates.py

@@ -84,21 +84,21 @@ def __lt__(self, other):
             return NotImplemented
         return (other._index - self._index) % 3 == 1
 
-    # TODO(#3388) Add documentation for Raises.
-    # pylint: disable=missing-raises-doc
     def on(self, *qubits: 'cirq.Qid') -> 'SingleQubitPauliStringGateOperation':
         """Returns an application of this gate to the given qubits.
 
         Args:
             *qubits: The collection of qubits to potentially apply the gate to.
+
+        Raises:
+            ValueError: If more than one qubit is acted upon.
         """
         if len(qubits) != 1:
             raise ValueError(f'Expected a single qubit, got <{qubits!r}>.')
         from cirq.ops.pauli_string import SingleQubitPauliStringGateOperation
 
         return SingleQubitPauliStringGateOperation(self, qubits[0])
 
-    # pylint: enable=missing-raises-doc
     @property
     def _canonical_exponent(self):
         """Overrides EigenGate._canonical_exponent in subclasses."""

cirq-core/cirq/ops/pauli_string_phasor.py

@@ -40,8 +40,6 @@ class PauliStringPhasor(pauli_string_raw_types.PauliStringGateOperation):
     their amplitude multiplied by e^(i pi exponent_pos).
     """
 
-    # TODO(#3388) Add documentation for Raises.
-    # pylint: disable=missing-raises-doc
     def __init__(
         self,
         pauli_string: ps.PauliString,
@@ -58,6 +56,10 @@ def __init__(
                 in the form of the t in (-1)**t = exp(i pi t).
             exponent_pos: How much to phase vectors in the positive eigenspace,
                 in the form of the t in (-1)**t = exp(i pi t).
+
+        Raises:
+            ValueError: If the given pauli string does not have eignevalues +1
+                or -1.
         """
         if pauli_string.coefficient == -1:
             pauli_string = -pauli_string
@@ -73,7 +75,6 @@ def __init__(
         self.exponent_neg = value.canonicalize_half_turns(exponent_neg)
         self.exponent_pos = value.canonicalize_half_turns(exponent_pos)
 
-    # pylint: enable=missing-raises-doc
     @property
     def exponent_relative(self) -> Union[int, float, sympy.Basic]:
         return value.canonicalize_half_turns(self.exponent_neg - self.exponent_pos)

cirq-core/cirq/optimizers/two_qubit_decompositions.py

@@ -199,19 +199,17 @@ def _kak_decomposition_to_operations(
     )
 
 
-# TODO(#3388) Add documentation for Args.
-# pylint: disable=missing-param-doc
 def _is_trivial_angle(rad: float, atol: float) -> bool:
     """Tests if a circuit for an operator exp(i*rad*XX) (or YY, or ZZ) can
     be performed with a whole CZ.
 
     Args:
         rad: The angle in radians, assumed to be in the range [-pi/4, pi/4]
+        atol: The absolute tolerance with which to make this judgement.
     """
     return abs(rad) < atol or abs(abs(rad) - np.pi / 4) < atol
 
 
-# pylint: enable=missing-param-doc
 def _parity_interaction(
     q0: 'cirq.Qid', q1: 'cirq.Qid', rads: float, atol: float, gate: Optional[ops.Gate] = None
 ):

cirq-core/cirq/protocols/act_on_protocol.py

@@ -88,8 +88,6 @@ def _act_on_(
         """
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def act_on(
     action: Union['cirq.Operation', 'cirq.Gate'],
     args: 'cirq.OperationTarget',
@@ -125,6 +123,10 @@ def act_on(
         Nothing. Results are communicated by editing `args`.
 
     Raises:
+        ValueError: If called on an operation and supplied qubits, if not called
+            on an operation and no qubits are supplied, or if `_act_on_` or
+             `_act_on_fallback_` returned something other than `True` or
+             `NotImplemented`.
         TypeError: Failed to act `action` on `args`.
     """
     is_op = isinstance(action, ops.Operation)
@@ -166,6 +168,3 @@ def act_on(
         f"Action type: {type(action)}\n"
         f"Action repr: {action!r}\n"
     )
-
-
-# pylint: enable=missing-raises-doc

cirq-core/cirq/protocols/approximate_equality_protocol.py

@@ -47,8 +47,6 @@ def _approx_eq_(self, other: Any, *, atol: Union[int, float]) -> bool:
         """
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def approx_eq(val: Any, other: Any, *, atol: Union[int, float] = 1e-8) -> bool:
     """Approximately compares two objects.
 
@@ -72,6 +70,10 @@ def approx_eq(val: Any, other: Any, *, atol: Union[int, float] = 1e-8) -> bool:
 
     Returns:
         True if objects are approximately equal, False otherwise.
+
+    Raises:
+        AttributeError: If there is insufficient information to determine whether
+            the objects are approximately equal.
     """
 
     # Check if val defines approximate equality via _approx_eq_. This takes
@@ -118,7 +120,6 @@ def approx_eq(val: Any, other: Any, *, atol: Union[int, float] = 1e-8) -> bool:
     return val == other
 
 
-# pylint: enable=missing-raises-doc
 def _approx_eq_iterables(val: Iterable, other: Iterable, *, atol: Union[int, float]) -> bool:
     """Iterates over arguments and calls approx_eq recursively.