More documentation fixes (#4654)

What do you do every night?  Fix more documentation lint errors pinky.

cirq-aqt/cirq_aqt/aqt_sampler.py

@@ -50,8 +50,6 @@ def __init__(self, remote_host: str, access_token: str):
         self.remote_host = remote_host
         self.access_token = access_token
 
-    # TODO(#3388) Add documentation for Raises.
-    # pylint: disable=missing-raises-doc
     def _generate_json(
         self,
         circuit: cirq.AbstractCircuit,
@@ -71,11 +69,14 @@ def _generate_json(
         qubits: list of qubits where the operation acts on.
 
         Args:
-            circuit: Circuit to be run
-            param_resolver: Param resolver for the
+            circuit: Circuit to be run.
+            param_resolver: Param resolver for resolving parameters in circuit.
 
         Returns:
-            json formatted string of the sequence
+            json formatted string of the sequence.
+
+        Raises:
+            RuntimeError: If the circuit is empty.
         """
 
         seq_list: List[
@@ -101,7 +102,6 @@ def _generate_json(
         json_str = json.dumps(seq_list)
         return json_str
 
-    # TODO(#3388) Add documentation for Raises.
     def _send_json(
         self,
         *,
@@ -128,6 +128,9 @@ def _send_json(
 
         Returns:
             Measurement results as an array of boolean.
+
+        Raises:
+            RuntimeError: If there was an unexpected response from the server.
         """
         header = {"Ocp-Apim-Subscription-Key": self.access_token, "SDK": "cirq"}
         response = put(
@@ -174,7 +177,6 @@ def _send_json(
                 measurements[i, j] = int(measurement_int_bin[j])
         return measurements
 
-    # pylint: enable=missing-raises-doc
     def run_sweep(
         self, program: cirq.AbstractCircuit, params: cirq.Sweepable, repetitions: int = 1
     ) -> List[cirq.Result]:

cirq-core/cirq/contrib/acquaintance/permutation.py

@@ -40,14 +40,13 @@
 LogicalMapping = Dict[LogicalMappingKey, LogicalIndex]
 
 
-# TODO(#3388) Add documentation for Args.
-# pylint: disable=missing-param-doc
 class PermutationGate(ops.Gate, metaclass=abc.ABCMeta):
     """A permutation gate indicates a change in the mapping from qubits to
     logical indices.
 
     Args:
-        swap_gate: the gate that swaps the indices mapped to by a pair of
+        num_qubits: The number of qubits the gate should act on.
+        swap_gate: The gate that swaps the indices mapped to by a pair of
             qubits (e.g. SWAP or fermionic swap).
     """
 
@@ -108,7 +107,6 @@ def _circuit_diagram_info_(
         return wire_symbols
 
 
-# pylint: enable=missing-param-doc
 class MappingDisplayGate(ops.Gate):
     """Displays the indices mapped to a set of wires."""
 
@@ -188,22 +186,20 @@ class LinearPermutationGate(PermutationGate):
     """A permutation gate that decomposes a given permutation using a linear
     sorting network."""
 
-    # TODO(#3388) Add documentation for Args.
-    # pylint: disable=missing-param-doc
     def __init__(
         self, num_qubits: int, permutation: Dict[int, int], swap_gate: 'cirq.Gate' = ops.SWAP
     ) -> None:
         """Initializes a linear permutation gate.
 
         Args:
+            num_qubits: The number of qubits to permute.
             permutation: The permutation effected by the gate.
             swap_gate: The swap gate used in decompositions.
         """
         super().__init__(num_qubits, swap_gate)
         PermutationGate.validate_permutation(permutation, num_qubits)
         self._permutation = permutation
 
-    # pylint: enable=missing-param-doc
     def permutation(self) -> Dict[int, int]:
         return self._permutation
 

cirq-core/cirq/contrib/paulistring/separate.py

@@ -19,20 +19,20 @@
 from cirq.contrib.paulistring.convert_gate_set import converted_gate_set
 
 
-# TODO(#3388) Add documentation for Args.
-# pylint: disable=missing-param-doc
 def convert_and_separate_circuit(
     circuit: circuits.Circuit,
     leave_cliffords: bool = True,
     atol: float = 1e-8,
 ) -> Tuple[circuits.Circuit, circuits.Circuit]:
-    """Converts any circuit into two circuits where (circuit_left+circuit_right)
-    is equivalent to the given circuit.
+    """Converts a circuit into two, one made of PauliStringPhasor and the other Clifford gates.
 
     Args:
         circuit: Any Circuit that cirq.google.optimized_for_xmon() supports.
             All gates should either provide a decomposition or have a known one
             or two qubit unitary matrix.
+        leave_cliffords: If set, single qubit rotations in the Clifford group
+                are not converted to SingleQubitCliffordGates.
+        atol: The absolute tolerance for the conversion.
 
     Returns:
         (circuit_left, circuit_right)
@@ -43,12 +43,12 @@ def convert_and_separate_circuit(
         SingleQubitCliffordGate and PauliInteractionGate gates.
         It also contains MeasurementGates if the
         given circuit contains measurements.
+
     """
     circuit = converted_gate_set(circuit, no_clifford_gates=not leave_cliffords, atol=atol)
     return pauli_string_half(circuit), regular_half(circuit)
 
 
-# pylint: enable=missing-param-doc
 def regular_half(circuit: circuits.Circuit) -> circuits.Circuit:
     """Return only the Clifford part of a circuit.  See
     convert_and_separate_circuit().

cirq-core/cirq/interop/quirk/cells/testing.py

@@ -20,8 +20,6 @@
 from cirq import quirk_url_to_circuit
 
 
-# TODO(#3388) Add summary line to docstring.
-# pylint: disable=docstring-first-line-empty
 def assert_url_to_circuit_returns(
     json_text: str,
     circuit: 'cirq.Circuit' = None,
@@ -31,7 +29,8 @@ def assert_url_to_circuit_returns(
     output_amplitudes_from_quirk: Optional[List[Dict[str, float]]] = None,
     maps: Optional[Dict[int, int]] = None,
 ):
-    """
+    """Assert that `quirk_url_to_circuit` functions correctly.
+
     Args:
         json_text: The part of the quirk URL after "#circuit=".
         circuit: The optional expected circuit. If specified and not
@@ -80,6 +79,3 @@ def assert_url_to_circuit_returns(
 
     if maps:
         cirq.testing.assert_equivalent_computational_basis_map(maps, parsed)
-
-
-# pylint: enable=docstring-first-line-empty

cirq-core/cirq/ion/convert_to_ion_gates.py

@@ -32,16 +32,17 @@ def __init__(self, ignore_failures: bool = False) -> None:
         self.ignore_failures = ignore_failures
         self.gateset = ion_device.get_ion_gateset()
 
-    # TODO(#3388) Add documentation for Raises.
-    # pylint: disable=missing-raises-doc
     def convert_one(self, op: ops.Operation) -> ops.OP_TREE:
         """Convert a single (one- or two-qubit) operation into ion trap native gates.
 
         Args:
-            op: gate operation to be converted
+            op: The gate operation to be converted.
 
         Returns:
-            the desired operation implemented with ion trap gates
+            The desired operations implemented with ion trap gates.
+
+        Raises:
+            TypeError: If the operation cannot be converted.
         """
 
         # Known gate name
@@ -80,7 +81,6 @@ def convert_one(self, op: ops.Operation) -> ops.OP_TREE:
             "or composite.".format(op.gate)
         )
 
-    # pylint: enable=missing-raises-doc
     def convert_circuit(self, circuit: circuits.Circuit) -> circuits.Circuit:
         new_circuit = circuits.Circuit()
         for moment in circuit:

cirq-core/cirq/ops/moment.py

@@ -137,8 +137,6 @@ def operation_at(self, qubit: raw_types.Qid) -> Optional['cirq.Operation']:
         else:
             return None
 
-    # TODO(#3388) Add documentation for Raises.
-    # pylint: disable=missing-raises-doc
     def with_operation(self, operation: 'cirq.Operation') -> 'cirq.Moment':
         """Returns an equal moment, but with the given op added.
 
@@ -147,6 +145,9 @@ def with_operation(self, operation: 'cirq.Operation') -> 'cirq.Moment':
 
         Returns:
             The new moment.
+
+        Raises:
+            ValueError: If the operation given overlaps a current operation in the moment.
         """
         if any(q in self._qubits for q in operation.qubits):
             raise ValueError(f'Overlapping operations: {operation}')
@@ -161,7 +162,6 @@ def with_operation(self, operation: 'cirq.Operation') -> 'cirq.Moment':
 
         return m
 
-    # TODO(#3388) Add documentation for Raises.
     def with_operations(self, *contents: 'cirq.OP_TREE') -> 'cirq.Moment':
         """Returns a new moment with the given contents added.
 
@@ -170,6 +170,9 @@ def with_operations(self, *contents: 'cirq.OP_TREE') -> 'cirq.Moment':
 
         Returns:
             The new moment.
+
+        Raises:
+            ValueError: If the contents given overlaps a current operation in the moment.
         """
         from cirq.ops import op_tree
 
@@ -192,7 +195,6 @@ def with_operations(self, *contents: 'cirq.OP_TREE') -> 'cirq.Moment':
 
         return m
 
-    # pylint: enable=missing-raises-doc
     def without_operations_touching(self, qubits: Iterable['cirq.Qid']) -> 'cirq.Moment':
         """Returns an equal moment, but without ops on the given qubits.
 
@@ -375,8 +377,6 @@ def __getitem__(self, key):
                     ops_to_keep.append(self._qubit_to_op[q])
             return Moment(frozenset(ops_to_keep))
 
-    # TODO(#3388) Add summary line to docstring.
-    # pylint: disable=docstring-first-line-empty
     def to_text_diagram(
         self: 'cirq.Moment',
         *,
@@ -385,8 +385,9 @@ def to_text_diagram(
         use_unicode_characters: bool = True,
         precision: Optional[int] = None,
         include_tags: bool = True,
-    ):
-        """
+    ) -> str:
+        """Create a text diagram for the moment.
+
         Args:
             xy_breakdown_func: A function to split qubits/qudits into x and y
                 components. For example, the default breakdown turns
@@ -469,7 +470,6 @@ def cleanup_key(key: Any) -> Any:
 
         return diagram.render()
 
-    # pylint: enable=docstring-first-line-empty
     def _commutes_(
         self, other: Any, *, atol: Union[int, float] = 1e-8
     ) -> Union[bool, NotImplementedType]:

cirq-core/cirq/sim/sparse_simulator_test.py

@@ -1174,10 +1174,9 @@ def test_random_seed_mixture_deterministic():
     )
 
 
-# TODO(#3388) Add summary line to docstring.
-# pylint: disable=docstring-first-line-empty
 def test_entangled_reset_does_not_break_randomness():
-    """
+    """Test for bad assumptions on caching the wave function on general channels.
+
     A previous version of cirq made the mistake of assuming that it was okay to
     cache the wavefunction produced by general channels on unrelated qubits
     before repeatedly sampling measurements. This test checks for that mistake.
@@ -1194,7 +1193,6 @@ def test_entangled_reset_does_not_break_randomness():
     assert 10 <= counts[1] <= 90
 
 
-# pylint: enable=docstring-first-line-empty
 def test_overlapping_measurements_at_end():
     a, b = cirq.LineQubit.range(2)
     circuit = cirq.Circuit(

cirq-core/cirq/testing/equivalent_repr_eval.py

@@ -15,8 +15,6 @@
 from typing import Any, Dict, Optional
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def assert_equivalent_repr(
     value: Any,
     *,
@@ -37,10 +35,11 @@ def assert_equivalent_repr(
             evaluating the repr.
         local_vals: Pre-defined values that should be in the local scope when
             evaluating the repr.
+
+    Raises:
+        AssertionError: If the assertion fails, or eval(repr(value)) raises an error.
     """
-    # pylint: disable=unused-variable
-    __tracebackhide__ = True
-    # pylint: enable=unused-variable
+    __tracebackhide__ = True  # pylint: disable=unused-variable
 
     global_vals = global_vals or {}
     local_vals = local_vals or {}
@@ -99,6 +98,3 @@ def assert_equivalent_repr(
         "{!r}.XXX must be equivalent to ({!r}).XXX, "
         "but it wasn't.".format(type(value), value, value)
     )
-
-
-# pylint: enable=missing-raises-doc

cirq-google/cirq_google/optimizers/convert_to_sqrt_iswap.py

@@ -51,12 +51,10 @@ def __init__(self, ignore_failures=False) -> None:
         super().__init__()
         self.ignore_failures = ignore_failures
 
-    # TODO(#3388) Add summary line to docstring.
-    # pylint: disable=docstring-first-line-empty
     def _convert_one(self, op: cirq.Operation) -> cirq.OP_TREE:
-        """
-        Decomposer intercept:  Let cirq decompose one-qubit gates,
-        intercept on 2-qubit gates if they are known gates.
+        """The main conversion method.
+
+        Let Cirq decompose one-qubit gates, intercept on 2-qubit gates if they are known gates.
         """
         if isinstance(op, cirq.GlobalPhaseOperation):
             return []
@@ -82,7 +80,6 @@ def _convert_one(self, op: cirq.Operation) -> cirq.OP_TREE:
 
         return NotImplemented
 
-    # pylint: enable=docstring-first-line-empty
     def _on_stuck_raise(self, bad):
         return TypeError(
             f"Don't know how to work with {bad}. "
@@ -265,11 +262,10 @@ def iswap_to_sqrt_iswap(a, b, turns):
     yield cirq.Z(b) ** -0.25
 
 
-# TODO(#3388) Add documentation for Args.
-# pylint: disable=missing-param-doc
 def swap_to_sqrt_iswap(a, b, turns):
-    """Implement the evolution of the hopping term using two sqrt_iswap gates
-     and single-qubit operations. Output unitary:
+    """Implement the evolution of a hopping term using two sqrt_iswap gates and single qubit gates.
+
+    Output unitary:
     [[1, 0,        0,     0],
      [0, g·c,    -i·g·s,  0],
      [0, -i·g·s,  g·c,    0],
@@ -279,8 +275,11 @@ def swap_to_sqrt_iswap(a, b, turns):
     Args:
         a: the first qubit
         b: the second qubit
-        theta: The rotational angle that specifies the gate, where
-        c = cos(π·t/2), s = sin(π·t/2), g = exp(i·π·t/2).
+        turns: The rotational angle that specifies the gate, where
+            c = cos(π·t/2), s = sin(π·t/2), g = exp(i·π·t/2).
+
+    Yields:
+        A `cirq.OP_TREE` representing the decomposition.
     """
     if not isinstance(turns, sympy.Basic) and _near_mod_n(turns, 1.0, 2):
         # Decomposition for cirq.SWAP
@@ -308,7 +307,6 @@ def swap_to_sqrt_iswap(a, b, turns):
     yield cirq.CZ.on(a, b) ** (-turns)
 
 
-# pylint: enable=missing-param-doc
 def fsim_gate(a, b, theta, phi):
     """FSimGate has a default decomposition in cirq to XXPowGate and YYPowGate,
     which is an awkward decomposition for this gate set.