still more docs

bandfit/bandfit.py

@@ -185,6 +185,11 @@ def detect_bands(data, *args, **kwargs):
 
 
 def plot_data_with_bands(data, bands):
+    """
+    Plot the measured band structure ``data`` together with the output
+    of :any:`detect_bands`.
+    """
+
     plt.matshow(data)
     ks = np.arange(data.shape[1])
 
@@ -193,6 +198,15 @@ def plot_data_with_bands(data, bands):
 
 
 def candidate(k, c, d, a, δb, k_scale, k_shift):
+    """
+    Returns the theoretical band structure as a function of ``k``
+    doubled so that upper and lower band can be fitted simultaneously.
+
+    The ``a,c,d`` parameters correspond to the parameters of the
+    hamiltonian and ``b = a * (1 + δb)`` so that the difference
+    between ``a`` and ``b`` can be constrained.  Additionally, the
+    ``k`` argument is scaled and shifted with ``k_scale,k_shift``.
+    """
     k = np.asarray(k[: k.size // 2]) * k_scale + k_shift
     energies = energy(k, a, a + δb * a, c, d)