Polish pass over the documentation (#1191)

Author: Strilanc

cirq/devices/grid_qubit.py

@@ -26,7 +26,7 @@ class GridQubit(ops.QubitId):
         GridQubit(0, 0) < GridQubit(0, 1) < GridQubit(1, 0) < GridQubit(1, 1)
     """
 
-    def __init__(self, row, col):
+    def __init__(self, row: int, col: int):
         self.row = row
         self.col = col
 

cirq/linalg/decompositions.py

@@ -271,7 +271,7 @@ def so4_to_magic_su2s(
 class KakDecomposition:
     """A convenient description of an arbitrary two-qubit operation.
 
-    Any two qubit operation U = can be decomposed into the form
+    Any two qubit operation U can be decomposed into the form
 
         U = g · (a1 ⊗ a0) · exp(i·(x·XX + y·YY + z·ZZ)) · (b1 ⊗ b0)
 

cirq/ops/common_gates.py

@@ -328,18 +328,19 @@ class MeasurementGate(raw_types.Gate):
 
     The measurement gate contains a key that is used to identify results
     of measurements.
-
-    Attributes:
-        key: The string key of the measurement.
-        invert_mask: A list of values indicating whether the corresponding
-            qubits should be flipped. The list's length must not be longer than
-            the number of qubits, but it is permitted to be shorted.
-            Qubits with indices past the end of the mask are not flipped.
     """
 
     def __init__(self,
                  key: str = '',
                  invert_mask: Tuple[bool, ...] = ()) -> None:
+        """
+        Args:
+            key: The string key of the measurement.
+            invert_mask: A list of values indicating whether the corresponding
+                qubits should be flipped. The list's length must not be longer
+                than the number of qubits, but it is permitted to be shorter.
+                Qubits with indices past the end of the mask are not flipped.
+        """
         self.key = key
         self.invert_mask = invert_mask or ()
 
@@ -474,16 +475,20 @@ class HPowGate(eigen_gate.EigenGate, gate_features.SingleQubitGate):
     """A Gate that performs a rotation around the X+Z axis of the Bloch sphere.
 
 
-    HPowGate()**t = HPowGate(exponent=t) is given by the matrix
+    The unitary matrix of ``HPowGate(exponent=t)`` is:
+
         [[g·(c-i·s/sqrt(2)), -i·g·s/sqrt(2)],
         [-i·g·s/sqrt(2)], g·(c+i·s/sqrt(2))]]
+
     where
+
         c = cos(π·t/2)
         s = sin(π·t/2)
         g = exp(i·π·t/2).
-    Note in particular that for t=1, this gives the Hadamard matrix.
 
-    `cirq.H`, the Hadamard gate, is an instance of this gate at exponent=1.
+    Note in particular that for `t=1`, this gives the Hadamard matrix.
+
+    `cirq.H`, the Hadamard gate, is an instance of this gate at `exponent=1`.
     """
 
     def _eigen_components(self):
@@ -575,7 +580,7 @@ class CZPowGate(eigen_gate.EigenGate,
 
         g = exp(i·π·t/2).
 
-    `cirq.Z``, the controlled Z gate, is an instance of this gate at
+    `cirq.CZ`, the controlled Z gate, is an instance of this gate at
     `exponent=1`.
     """
 

cirq/ops/matrix_gates.py

@@ -29,8 +29,9 @@ def _phase_matrix(turns: float) -> np.ndarray:
 class SingleQubitMatrixGate(raw_types.Gate):
     """A 1-qubit gate defined by its matrix.
 
-    More general than specialized classes like ZGate, but more expensive and
-    more float-error sensitive to work with (due to using eigendecompositions).
+    More general than specialized classes like `ZPowGate`, but more expensive
+    and more float-error sensitive to work with (due to using
+    eigendecompositions).
     """
 
     def __init__(self, matrix: np.ndarray) -> None:
@@ -108,8 +109,9 @@ def __str__(self):
 class TwoQubitMatrixGate(raw_types.Gate):
     """A 2-qubit gate defined only by its matrix.
 
-    More general than specialized classes like CZGate, but more expensive and
-    more float-error sensitive to work with (due to using eigendecompositions).
+    More general than specialized classes like `CZPowGate`, but more expensive
+    and more float-error sensitive to work with (due to using
+    eigendecompositions).
     """
 
     def __init__(self, matrix: np.ndarray) -> None:

cirq/ops/named_qubit.py

@@ -18,10 +18,10 @@
 class NamedQubit(raw_types.QubitId):
     """A qubit identified by name.
 
-    By default, NamedQubit has a lexicographic order except that numbers within
+    By default, NamedQubit has a lexicographic order. However, numbers within
     the name are handled correctly. So, for example, if you print a circuit
-    containing cirq.NamedQubit('qubit22') and cirq.NamedQubit('qubit3'), the
-    wire for 'qubit3' will come before 'qubit22'.
+    containing `cirq.NamedQubit('qubit22')` and `cirq.NamedQubit('qubit3')`, the
+    wire for 'qubit3' will correctly come before 'qubit22'.
     """
 
     def __init__(self, name: str) -> None:

cirq/ops/raw_types.py

@@ -27,11 +27,11 @@ class QubitId(metaclass=abc.ABCMeta):
     """Identifies a qubit. Child classes implement specific types of qubits.
 
     The main criteria that a "qubit id" must satisfy is *comparability*. Child
-    classes meet this criteria by implementing the _comparison_key method. For
-    example, cirq.LineQubit's _comparison_key method returns `self.x`. This
+    classes meet this criteria by implementing the `_comparison_key` method. For
+    example, `cirq.LineQubit`'s `_comparison_key` method returns `self.x`. This
     ensures that line qubits with the same `x` are equal, and that line qubits
-    will be sorted ascending by `x`. QubitId implements all equality,
-    comparison, and hashing methods via`_comparison_key`.
+    will be sorted ascending by `x`. `QubitId` implements all equality,
+    comparison, and hashing methods via `_comparison_key`.
     """
 
     @abc.abstractmethod

cirq/ops/three_qubit_gates.py

@@ -34,7 +34,7 @@ class CCZPowGate(eigen_gate.EigenGate,
                  gate_features.InterchangeableQubitsGate):
     """A doubly-controlled-Z that can be raised to a power.
 
-    The matrix of CCZ**t is diag(1, 1, 1, 1, 1, 1, 1, exp(i pi t)).
+    The matrix of `CCZ**t` is `diag(1, 1, 1, 1, 1, 1, 1, exp(i pi t))`.
     """
 
     def _eigen_components(self):
@@ -126,7 +126,8 @@ class CCXPowGate(eigen_gate.EigenGate,
                  gate_features.InterchangeableQubitsGate):
     """A Toffoli (doubly-controlled-NOT) that can be raised to a power.
 
-    The matrix of CCX**t is an 8x8 identity except the bottom right 2x2 is X**t.
+    The matrix of `CCX**t` is an 8x8 identity except the bottom right 2x2 area
+    is the matrix of `X**t`.
     """
 
     def _eigen_components(self):

cirq/sim/wave_function.py

@@ -62,7 +62,7 @@ def density_matrix_from_state_vector(
     state: Sequence,
     indices: Iterable[int] = None
 ) -> np.ndarray:
-    """Returns the density matrix of the wavefunction.
+    r"""Returns the density matrix of the wavefunction.
 
     Calculate the density matrix for the system on the given qubit
     indices, with the qubits not in indices that are present in state
@@ -71,12 +71,18 @@ def density_matrix_from_state_vector(
     convention of numpy.kron.
 
     For example:
+
         state = np.array([1/np.sqrt(2), 1/np.sqrt(2)], dtype=np.complex64)
         indices = None
-        gives us \rho = \begin{bmatrix}
-                            0.5 & 0.5
-                            0.5 & 0.5
-                        \end{bmatrix}
+
+    gives us
+
+        $$
+        \rho = \begin{bmatrix}
+                0.5 & 0.5
+                0.5 & 0.5
+            \end{bmatrix}
+        $$
 
     Args:
         state: A sequence representing a wave function in which
@@ -120,8 +126,9 @@ def dirac_notation(state: Sequence, decimals: int=2) -> str:
     """Returns the wavefunction as a string in Dirac notation.
 
     For example:
+
         state = np.array([1/np.sqrt(2), 1/np.sqrt(2)], dtype=np.complex64)
-        print(pretty_state(state)) -> 0.71|0⟩ + 0.71|1⟩
+        print(dirac_notation(state)) -> 0.71|0⟩ + 0.71|1⟩
 
     Args:
         state: A sequence representing a wave function in which the ordering