[API docs] Gate api docs cleanup. (quantumlib#5503)

Clean up docs for `Gate`.

cirq/ops/raw_types.py

@@ -211,7 +211,7 @@ def validate_args(self, qubits: Sequence['cirq.Qid']) -> None:
         Args:
             qubits: The sequence of qubits to potentially apply the gate to.
 
-        Throws:
+        Raises:
             ValueError: The gate can't be applied to the qubits.
         """
         _validate_qid_shape(self, qubits)
@@ -221,6 +221,9 @@ def on(self, *qubits: Qid) -> 'Operation':
 
         Args:
             *qubits: The collection of qubits to potentially apply the gate to.
+
+        Returns: a `cirq.Operation` which is this gate applied to the given
+            qubits.
         """
         return ops.gate_operation.GateOperation(self, list(qubits))
 
@@ -277,6 +280,16 @@ def on_each(self, *targets: Union[Qid, Iterable[Any]]) -> List['cirq.Operation']
     def wrap_in_linear_combination(
         self, coefficient: Union[complex, float, int] = 1
     ) -> 'cirq.LinearCombinationOfGates':
+        """Returns a LinearCombinationOfGates with this gate.
+
+        Args:
+            coefficient: number coefficient to use in the resulting
+                `cirq.LinearCombinationOfGates` object.
+
+        Returns:
+            `cirq.LinearCombinationOfGates` containing self with a
+                coefficient of `coefficient`.
+        """
         return ops.linear_combinations.LinearCombinationOfGates({self: coefficient})
 
     def __add__(
@@ -328,7 +341,16 @@ def __call__(self, *qubits: Qid, **kwargs):
         return self.on(*qubits)
 
     def with_probability(self, probability: 'cirq.TParamVal') -> 'cirq.Gate':
+        """Creates a probabalistic channel with this gate.
 
+        Args:
+            probability: floating value between 0 and 1, giving the probability
+                this gate is applied.
+
+        Returns:
+            `cirq.RandomGateChannel` that applies `self` with probability
+                `probability` and the identity with probability `1-p`.
+        """
         if probability == 1:
             return self
         return ops.random_gate_channel.RandomGateChannel(sub_gate=self, probability=probability)
@@ -342,16 +364,18 @@ def controlled(
         """Returns a controlled version of this gate. If no arguments are
         specified, defaults to a single qubit control.
 
-         num_controls: Total number of control qubits.
-         control_values: For which control qubit values to apply the sub
-             gate.  A sequence of length `num_controls` where each
-             entry is an integer (or set of integers) corresponding to the
-             qubit value (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.
+
+        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.
         """
 
         if num_controls == 0: