add docstrings

qiskit/synthesis/__init__.py

@@ -84,6 +84,11 @@
 
 .. autofunction:: generate_basic_approximations
 
+Basis Change Synthesis
+======================
+
+.. autofunction:: synth_qft_line
+
 """
 
 from .evolution import (

qiskit/synthesis/qft/qft_decompose_lnn.py

@@ -20,7 +20,27 @@
 
 def synth_qft_line(num_qubits, do_swaps=True, approximation_degree=0):
     """Synthesis of a QFT circuit for a linear nearest neighbor connectivity.
-    Based on Fowler et al. Fig 2.b from https://arxiv.org/abs/quant-ph/0402196"""
+    Based on Fig 2.b in Fowler et al. [1].
+
+    Note that this method *reverts* the order of qubits in the circuit,
+    compared to the original QFT code.
+    Hence, the default value of do_swaps parameter is True,
+    since it produces a circuit with fewer CX gates.
+
+    Args:
+        num_qubits (int): The number of qubits on which the QFT acts.
+        approximation_degree (int): The degree of approximation (0 for no approximation).
+        do_swaps (bool): Whether to include the final swaps in the QFT.
+
+    Return:
+        QuantumCircuit: a circuit implementation of the QFT circuit.
+
+    Reference:
+        1. A. G. Fowler, S. J. Devitt, and L. C. L. Hollenberg,
+           *Implementation of Shor's algorithm on a linear nearest neighbour qubit array*,
+           Quantum Info. Comput. 4, 4 (July 2004), 237–251.
+           `arXiv:quant-ph/0402196 [quant-ph] <https://arxiv.org/abs/quant-ph/0402196>`_
+    """
 
     qc = QuantumCircuit(num_qubits)
 
@@ -38,7 +58,7 @@ def synth_qft_line(num_qubits, do_swaps=True, approximation_degree=0):
 
     if not do_swaps:
         # Add a reversal network for LNN connectivity in depth 2*n+2,
-        # based on Kutin at al., https://arxiv.org/abs/quant-ph/0701194, Section 5
+        # based on Kutin at al., https://arxiv.org/abs/quant-ph/0701194, Section 5.
         for _ in range((num_qubits + 1) // 2):
             qc = _append_cx_stage1(qc, num_qubits)
             qc = _append_cx_stage2(qc, num_qubits)