Reducing documentation lint errors even further

cirq-core/cirq/_compat.py

@@ -464,19 +464,19 @@ def _deduped_module_warn_or_error(old_module_name: str, new_module_name: str, de
     )
 
 
-# TODO(#3388) Add documentation for Args.
-# pylint: disable=missing-param-doc
 class DeprecatedModuleFinder(importlib.abc.MetaPathFinder):
     """A module finder to handle deprecated module references.
 
     It sends a deprecation warning when a deprecated module is asked to be found.
     It is meant to be used as a wrapper around existing MetaPathFinder instances.
 
     Args:
-        finder: the finder to wrap.
-        new_module_name: the new module's fully qualified name
-        old_module_name: the deprecated module's fully qualified name
-        deadline: the deprecation deadline
+        finder: The finder to wrap.
+        new_module_name: The new module's fully qualified name.
+        old_module_name: The deprecated module's fully qualified name.
+        deadline: The deprecation deadline.
+        broken_module_exception: If specified, an exception to throw if
+            the module is found.
     """
 
     def __init__(
@@ -576,7 +576,6 @@ def find_spec(self, fullname: str, path: Any = None, target: Any = None) -> Any:
         return spec
 
 
-# pylint: enable=missing-param-doc
 class _BrokenModule(ModuleType):
     def __init__(self, name, exc):
         self.exc = exc

cirq-core/cirq/devices/noise_model.py

@@ -38,21 +38,21 @@ class NoiseModel(metaclass=value.ABCMetaImplementAnyOneOf):
     dynamically rewrite the program they are simulating.
     """
 
-    # TODO(#3388) Add documentation for Raises.
-    # pylint: disable=missing-raises-doc
     @classmethod
     def from_noise_model_like(cls, noise: 'cirq.NOISE_MODEL_LIKE') -> 'cirq.NoiseModel':
         """Transforms an object into a noise model if umambiguously possible.
 
         Args:
-            noise: ``None``, a ``cirq.NoiseModel``, or a single qubit operation.
+            noise: `None`, a `cirq.NoiseModel`, or a single qubit operation.
 
         Returns:
-            ``cirq.NO_NOISE`` when given ``None``,
-            ``cirq.ConstantQubitNoiseModel(gate)`` when given a single qubit
-            gate, or the given value if it is already a ``cirq.NoiseModel``.
+            `cirq.NO_NOISE` when given `None`,
+            `cirq.ConstantQubitNoiseModel(gate)` when given a single qubit
+            gate, or the given value if it is already a `cirq.NoiseModel`.
 
         Raises:
+            ValueError: If noise is a `cirq.Gate` that acts on more than one
+                qubit.
             TypeError: The input is not a ``cirq.NOISE_MODE_LIKE``.
         """
         if noise is None:
@@ -74,7 +74,6 @@ def from_noise_model_like(cls, noise: 'cirq.NOISE_MODEL_LIKE') -> 'cirq.NoiseMod
             'or a single qubit gate). Got {!r}'.format(noise)
         )
 
-    # pylint: enable=missing-raises-doc
     def is_virtual_moment(self, moment: 'cirq.Moment') -> bool:
         """Returns true iff the given moment is non-empty and all of its
         operations are virtual.

cirq-core/cirq/experiments/single_qubit_readout_calibration.py

@@ -105,8 +105,6 @@ def estimate_single_qubit_readout_errors(
     )
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def estimate_parallel_single_qubit_readout_errors(
     sampler: 'cirq.Sampler',
     *,
@@ -147,6 +145,11 @@ def estimate_parallel_single_qubit_readout_errors(
         if there did not exist a trial where a given qubit was set to |0〉,
         the zero-state error will be set to `nan` (not a number).  Likewise
         for qubits with no |1〉trial and one-state error.
+
+    Raises:
+        ValueError: If the number of trials, repetitions, or trials_per batch is
+            negative, or if bit_strings is not a numpy array or of the wrong
+            shape.
     """
     qubits = list(qubits)
 
@@ -237,6 +240,3 @@ def estimate_parallel_single_qubit_readout_errors(
         repetitions=repetitions,
         timestamp=timestamp,
     )
-
-
-# pylint: enable=missing-raises-doc

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

@@ -48,8 +48,6 @@ class QuirkArithmeticOperation(ops.ArithmeticOperation):
     and ensuring the new target register value is normalized modulo the modulus.
     """
 
-    # TODO(#3388) Add documentation for Raises.
-    # pylint: disable=missing-raises-doc
     def __init__(
         self,
         identifier: str,
@@ -63,6 +61,10 @@ def __init__(
             target: The target qubit register.
             inputs: Qubit registers (or classical constants) that
                 determine what happens to the target.
+
+        Raises:
+            ValueError: If given overlapping registers, or the target is too
+                small for a modular operation with too small modulus.
         """
         self.identifier = identifier
         self.target: Tuple['cirq.Qid', ...] = tuple(target)
@@ -85,7 +87,6 @@ def __init__(
             if over:
                 raise ValueError(f'Target too small for modulus.\nTarget: {target}\nModulus: {r}')
 
-    # pylint: enable=missing-raises-doc
     @property
     def operation(self) -> '_QuirkArithmeticCallable':
         return ARITHMETIC_OP_TABLE[self.identifier]

cirq-core/cirq/protocols/json_serialization.py

@@ -160,8 +160,7 @@ class name via a dot (.)
 
 
 # Copying the Python API, whose usage of `repr` annoys pylint.
-# TODO(#3388) Add documentation for Args.
-# pylint: disable=redefined-builtin, missing-param-doc
+# pylint: disable=redefine-builtin
 def json_serializable_dataclass(
     _cls: Optional[Type] = None,
     *,
@@ -187,11 +186,16 @@ def json_serializable_dataclass(
     `return dataclass_json_dict(self)`.
 
     Args:
+        _cls: The class to add JSON serializatin to.
         namespace: An optional prefix to the value associated with the
             key "cirq_type". The namespace name will be joined with the
             class name via a dot (.)
-        init, repr, eq, order, unsafe_hash, frozen: Forwarded to the
-            ``dataclass`` constructor.
+        init: Forwarded to the `dataclass` constructor.
+        repr: Forwarded to the `dataclass` constructor.
+        eq: Forwarded to the `dataclass` constructor.
+        order: Forwarded to the `dataclass` constructor.
+        unsafe_hash: Forwarded to the `dataclass` constructor.
+        frozen: Forwarded to the `dataclass` constructor.
     """
 
     def wrap(cls):
@@ -215,7 +219,7 @@ def wrap(cls):
     return wrap(_cls)
 
 
-# pylint: enable=redefined-builtin, missing-param-doc
+# pylint: enable=redefine-builtin
 def dataclass_json_dict(obj: Any, namespace: str = None) -> Dict[str, Any]:
     """Return a dictionary suitable for _json_dict_ from a dataclass.
 
@@ -589,8 +593,6 @@ def default(self, o):
 
 
 # pylint: enable=function-redefined
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def read_json(
     file_or_fn: Union[None, IO, pathlib.Path, str] = None,
     *,
@@ -614,6 +616,10 @@ def read_json(
             by pre-pending custom resolvers. Each resolver should return `None`
             to indicate that it cannot resolve the given cirq_type and that
             the next resolver should be tried.
+
+    Raises:
+        ValueError: If either none of `file_or_fn` and `json_text` is specified,
+            or both are specified.
     """
     if (file_or_fn is None) == (json_text is None):
         raise ValueError('Must specify ONE of "file_or_fn" or "json".')
@@ -636,7 +642,6 @@ def obj_hook(x):
     return json.load(cast(IO, file_or_fn), object_hook=obj_hook)
 
 
-# pylint: enable=missing-raises-doc
 def to_json_gzip(
     obj: Any,
     file_or_fn: Union[None, IO, pathlib.Path, str] = None,

cirq-core/cirq/sim/act_on_state_vector_args.py

@@ -81,14 +81,13 @@ def swap_target_tensor_for(self, new_target_tensor: np.ndarray):
             self.available_buffer = self.target_tensor
         self.target_tensor = new_target_tensor
 
-    # TODO(#3388) Add documentation for Args.
-    # pylint: disable=missing-param-doc
     def subspace_index(
         self, axes: Sequence[int], little_endian_bits_int: int = 0, *, big_endian_bits_int: int = 0
     ) -> Tuple[Union[slice, int, 'ellipsis'], ...]:
         """An index for the subspace where the target axes equal a value.
 
         Args:
+            axes: The qubits that are specified by the index bits.
             little_endian_bits_int: The desired value of the qubits at the
                 targeted `axes`, packed into an integer. The least significant
                 bit of the integer is the desired bit for the first axis, and
@@ -99,7 +98,6 @@ def subspace_index(
                 applies but in a different basis. For example, if the target
                 axes have dimension [a:2, b:3, c:2] then the integer 10
                 decomposes into [a=0, b=2, c=1] via 7 = 1*(3*2) +  2*(2) + 0.
-
             big_endian_bits_int: The desired value of the qubits at the
                 targeted `axes`, packed into an integer. The most significant
                 bit of the integer is the desired bit for the first axis, and
@@ -136,7 +134,6 @@ def subspace_index(
             qid_shape=self.target_tensor.shape,
         )
 
-    # pylint: enable=missing-param-doc
     def _act_on_fallback_(
         self,
         action: Union['cirq.Operation', 'cirq.Gate'],

cirq-core/cirq/sim/mux.py

@@ -99,8 +99,6 @@ def _to_circuit(program: 'cirq.CIRCUIT_LIKE') -> 'cirq.Circuit':
     return cast('cirq.Circuit', result)
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def final_state_vector(
     program: 'cirq.CIRCUIT_LIKE',
     *,
@@ -137,6 +135,10 @@ def final_state_vector(
         the amplitudes in np.kron order, where the order of arguments to kron
         is determined by the qubit order argument (which defaults to just
         sorting the qubits that are present into an ascending order).
+
+    Raises:
+        ValueError: If the program doesn't have a well defined final state because
+            it has non-unitary gates.
     """
     circuit_like = _to_circuit(program)
 
@@ -159,7 +161,6 @@ def final_state_vector(
     return result.state_vector()
 
 
-# pylint: enable=missing-raises-doc
 def sample_sweep(
     program: 'cirq.Circuit',
     params: study.Sweepable,

cirq-google/cirq_google/calibration/workflow.py

@@ -480,8 +480,6 @@ def prepare_floquet_characterization_for_moments(
     )
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def prepare_characterization_for_operations(
     circuit: Union[cirq.Circuit, Iterable[cirq.Circuit]],
     options: PhasedFSimCalibrationOptions[RequestT],
@@ -524,6 +522,7 @@ def prepare_characterization_for_operations(
     Raises:
         IncompatibleMomentError: When circuit contains a moment with operations other than the
             operations matched by gates_translator, or it mixes a single qubit and two qubit gates.
+        ValueError: If unable to cover all interactions with a half grid staggered pattern.
     """
 
     circuits = [circuit] if isinstance(circuit, cirq.Circuit) else circuit
@@ -548,7 +547,6 @@ def prepare_characterization_for_operations(
     return characterizations
 
 
-# pylint: enable=missing-raises-doc
 def prepare_floquet_characterization_for_operations(
     circuit: Union[cirq.Circuit, Iterable[cirq.Circuit]],
     options: FloquetPhasedFSimCalibrationOptions = WITHOUT_CHI_FLOQUET_PHASED_FSIM_CHARACTERIZATION,
@@ -600,8 +598,6 @@ def prepare_floquet_characterization_for_operations(
     )
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def _extract_all_pairs_to_characterize(
     circuits: Iterable[cirq.Circuit],
     gates_translator: Callable[[cirq.Gate], Optional[PhaseCalibratedFSimGate]],
@@ -620,6 +616,10 @@ def _extract_all_pairs_to_characterize(
         Tuple with set of all two-qubit interacting pairs and a common gate that represents those
         interactions. The gate can be used for characterization purposes. If no interactions are
         present the gate is None.
+
+    Raises:
+        ValueError: If multiple types of two qubit gates appear in the (possibly translated)
+            circuits.
     """
 
     all_pairs: Set[Tuple[cirq.Qid, cirq.Qid]] = set()
@@ -649,7 +649,6 @@ def _extract_all_pairs_to_characterize(
     return all_pairs, common_gate
 
 
-# pylint: enable=missing-raises-doc
 def _append_into_calibrations_if_missing(
     calibration: RequestT,
     calibrations: List[RequestT],
@@ -785,8 +784,6 @@ def _run_local_calibrations_via_sampler(
     ]
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def run_calibrations(
     calibrations: Sequence[PhasedFSimCalibrationRequest],
     sampler: Union[Engine, cirq.Sampler],
@@ -815,6 +812,11 @@ def run_calibrations(
 
     Returns:
         List of PhasedFSimCalibrationResult for each requested calibration.
+
+    Raises:
+        ValueError: If less than one layers was requested to be calibrated, if calibrations of
+            different types was supplied, if no `processor_id` or `gate_set` is provided, or
+            if the calibration / sampler combo is not supported.
     """
     if max_layers_per_request < 1:
         raise ValueError(
@@ -874,7 +876,6 @@ def run_calibrations(
     )
 
 
-# pylint: enable=missing-raises-doc
 def make_zeta_chi_gamma_compensation_for_moments(
     circuit: Union[cirq.Circuit, CircuitWithCalibration],
     characterizations: List[PhasedFSimCalibrationResult],
@@ -1047,8 +1048,6 @@ def _make_zeta_chi_gamma_compensation(
     return CircuitWithCalibration(compensated, compensated_moment_to_calibration)
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def _find_moment_zeta_chi_gamma_corrections(
     moment: cirq.Moment,
     characterization_index: Optional[int],
@@ -1076,6 +1075,14 @@ def _find_moment_zeta_chi_gamma_corrections(
            characterization index that matches the original decomposed gate. None when no gate
            was decomposed.
          - other: the remaining gates that were not decomposed.
+
+    Raises:
+        IncompatibleMomentError: If a moment has operations different than `cirq.GateOperation`,
+            if it contains an unsupported greater than one qubit operation, if parameters are
+            missing, if the engine gate does not match the `parameters` gate, or if there is
+            missing characterization data for a pair of qubits.
+        ValueError: If parameter is not supplied, if the translated engine gate does not match
+            the one in parameters, or if pair parameters cannot be obtained.
     """
     default_phases = PhasedFSimCharacterization(zeta=0.0, chi=0.0, gamma=0.0)
 
@@ -1131,7 +1138,6 @@ def _find_moment_zeta_chi_gamma_corrections(
     return decompositions, decompositions_moment_to_calibration, other
 
 
-# pylint: enable=missing-raises-doc
 @dataclasses.dataclass(frozen=True)
 class FSimPhaseCorrections:
     """Operations that compensate for zeta, chi and gamma angles of an approximate FSimGate gate.

cirq-google/cirq_google/optimizers/two_qubit_gates/math_utils.py

@@ -214,8 +214,6 @@ def in_weyl_chamber(kak_vec: np.ndarray) -> np.ndarray:
     return np.logical_and.reduce((x_inside, y_inside, z_inside))
 
 
-# TODO(#3388) Add documentation for Raises.
-# pylint: disable=missing-raises-doc
 def weyl_chamber_mesh(spacing: float) -> np.ndarray:
     """Cubic mesh of points in the Weyl chamber.
 
@@ -225,6 +223,10 @@ def weyl_chamber_mesh(spacing: float) -> np.ndarray:
     Returns:
         np.ndarray of shape (N,3) corresponding to the points in the Weyl
         chamber.
+
+    Raises:
+        ValueError: If the spacing is so small (less than 1e-3) that this
+            would build a mesh of size about 1GB.
     """
     if spacing < 1e-3:  # memory required ~ 1 GB
         raise ValueError(f'Generating a mesh with spacing {spacing} may cause system to crash.')
@@ -238,7 +240,6 @@ def weyl_chamber_mesh(spacing: float) -> np.ndarray:
     return mesh_points[in_weyl_chamber(mesh_points)]
 
 
-# pylint: enable=missing-raises-doc
 _XX = np.zeros((4, 4))
 _XX[(0, 1, 2, 3), (3, 2, 1, 0)] = 1
 _ZZ = np.diag([1, -1, -1, 1])