Enable missing argument in docstring lint (Qiskit#15721)

* Enable missing argument in docstring lint

In the recently merged Qiskit#15603 we migrated from pylint to use
ruff. During the development of that PR the rule group "D" for rules
derived from pydocstyle was investigated but the full rule group was
overly pedantic and even with disabling the most egregious rules also
changed the docs for the worse (at least by autofixing many rules) so
that sphinx would not succesfully build after applying the fixes. So
during Qiskit#15603 the changes for this rule group were reverted. However,
one of the useful rules from that group D417 which checks that all
arguments are documented. This rule found real issues in the
documentation and it is worthwhile to enable it. This commit enables the
rule in our ruff checks and fixes the issues associated with.

During this process ruff flagged one place in the `__call__` method
docstring for the `TwoQubitControlledUDecomposer` class has not
documented several arguments on the method. However, these arguments
are unused currently. It is apparently trying to match the `__call__`
signature of the other two qubit decomposers but is not using most of
the arguments. Most could be conceivably supported by
`TwoQubitControlledUDecomposer` and it's not clear why they were added.
But, for this PR I didn't want to look into adding the support as it was
out of scope. For the time being this PR suppresses the ruff rule and
adds a TODO comment to start using the unused arguments.

* Update filename docstring

* Revise wording on state visualization filename arg

Author: mtreinish

pyproject.toml

@@ -347,6 +347,8 @@ select = [
     "INP",
     # flake8-print
     "T20",
+    # Missing arguments in docstring
+    "D417",
 ]
 ignore = [
     "E402",  # module-import-not-at-top-of-file false positives with module docs

qiskit/circuit/controlflow/box.py

@@ -154,6 +154,9 @@ def __init__(
             duration: the final duration of the box.
             unit: the unit of ``duration``.
             label: an optional label for the box.
+            annotations: any :class:`.Annotation`\\ s to apply to the box.  In cases where order
+                is important, annotations are to be interpreted in the same order they appear in
+                the iterable.
         """
         self._circuit = circuit
         self._duration = duration

qiskit/circuit/controlflow/switch_case.py

@@ -70,6 +70,7 @@ def __init__(
             cases: an ordered iterable of the corresponding value of the ``target`` and the circuit
                 block that should be executed if this is matched.  There is no fall-through between
                 blocks, and the order matters.
+            label: An optional label for identifying the instruction.
         """
 
         from qiskit.circuit import QuantumCircuit

qiskit/circuit/duration.py

@@ -47,7 +47,7 @@ def convert_durations_to_dt(qc: QuantumCircuit, dt_in_sec: float, inplace=True):
 
     Returns a new circuit if `inplace=False`.
 
-    Parameters:
+    Args:
         qc (QuantumCircuit): Duration of dt in seconds used for conversion.
         dt_in_sec (float): Duration of dt in seconds used for conversion.
         inplace (bool): All durations are converted inplace or return new circuit.

qiskit/circuit/library/arithmetic/adders/adder.py

@@ -100,6 +100,7 @@ def __init__(self, num_state_qubits: int, label: str | None = None) -> None:
         Args:
             num_state_qubits: The number of qubits in each of the registers.
             name: The name of the circuit.
+            label: An optional label for identifying the instruction.
         """
         if num_state_qubits < 1:
             raise ValueError("Need at least 1 state qubit.")
@@ -155,6 +156,7 @@ def __init__(self, num_state_qubits: int, label: str | None = None) -> None:
         Args:
             num_state_qubits: The number of qubits in each of the registers.
             name: The name of the circuit.
+            label: An optional label for identifying the instruction.
         """
         if num_state_qubits < 1:
             raise ValueError("Need at least 1 state qubit.")
@@ -211,6 +213,7 @@ def __init__(self, num_state_qubits: int, label: str | None = None) -> None:
         Args:
             num_state_qubits: The number of qubits in each of the registers.
             name: The name of the circuit.
+            label: An optional label for identifying the instruction.
         """
         if num_state_qubits < 1:
             raise ValueError("Need at least 1 state qubit.")

qiskit/circuit/library/arithmetic/linear_pauli_rotations.py

@@ -93,7 +93,7 @@ def slope(self, slope: float) -> None:
         """Set the multiplicative factor of the rotation angles.
 
         Args:
-            The slope of the rotation angles.
+            slope: The slope of the rotation angles.
         """
         if self._slope is None or slope != self._slope:
             self._invalidate()

qiskit/circuit/library/arithmetic/multipliers/multiplier.py

@@ -151,7 +151,7 @@ def __init__(
             num_result_qubits: The number of result qubits to limit the output to.
                 Default value is ``2 * num_state_qubits`` to represent any possible
                 result from the multiplication of the two inputs.
-            name: The name of the circuit.
+            label: The optional string label to apply to the instruction.
         Raises:
             ValueError: If ``num_state_qubits`` is smaller than 1.
             ValueError: If ``num_result_qubits`` is smaller than ``num_state_qubits``.

qiskit/circuit/library/arithmetic/polynomial_pauli_rotations.py

@@ -206,7 +206,7 @@ def coeffs(self, coeffs: list[float]) -> None:
         ``coeffs[i]`` is the coefficient of the i-th power of x.
 
         Args:
-            The coefficients of the polynomial.
+            coeffs: The coefficients of the polynomial.
         """
         self._invalidate()
         self._coeffs = coeffs

qiskit/circuit/library/n_local/n_local.py

@@ -446,7 +446,7 @@ def num_qubits(self, num_qubits: int) -> None:
         """Set the number of qubits for the n-local circuit.
 
         Args:
-            The new number of qubits.
+            num_qubits: The new number of qubits.
         """
         if self._num_qubits != num_qubits:
             # invalidate the circuit
@@ -666,7 +666,7 @@ def ordered_parameters(self, parameters: ParameterVector | list[Parameter]) -> N
         """Set the parameters used in the underlying circuit.
 
         Args:
-            The parameters to be used in the underlying circuit.
+            parameters: The parameters to be used in the underlying circuit.
 
         Raises:
             ValueError: If the length of ordered parameters does not match the number of

qiskit/circuit/library/standard_gates/x.py

@@ -1243,15 +1243,18 @@ def __init__(
     ):
         """
         Args:
+            num_ctrl_qubits: Number of controls to add. Defaults to ``1``.
             dirty_ancillas: when set to ``True``, the method applies an optimized multicontrolled-X gate
                 up to a relative phase using dirty ancillary qubits with the properties of lemmas 7 and 8
                 from arXiv:1501.06911, with at most 8*k - 6 CNOT gates.
                 For k within the range {1, ..., ceil(n/2)}. And for n representing the total number of
                 qubits.
+            label: Optional gate label. Defaults to ``None``.
+            ctrl_state: The control state of the gate, specified either as an integer or a bitstring
+                (e.g. ``"110"``). If ``None``, defaults to the all-ones state ``2**num_ctrl_qubits - 1``
             relative_phase: when set to ``True``, the method applies the optimized multicontrolled-X gate
                 up to a relative phase, in a way that, by lemma 7 of arXiv:1501.06911, the relative
                 phases of the ``action part`` cancel out with the phases of the ``reset part``.
-
             action_only: when set to ``True``, the method applies only the action part of lemma 8
                 from arXiv:1501.06911.