add examples for functions returning functions

kwant/physics/dispersion.py

@@ -19,6 +19,14 @@ class Bands(object):
     (currently this must be a scalar as all infinite systems are quasi-1-d), it
     returns a NumPy array containing the eigenenergies of all modes at this
     momentum
+
+    Examples
+    --------
+    >>> bands = kwant.physics.Bands(some_sys)
+    >>> momenta = numpy.linspace(-numpy.pi, numpy.pi, 101)
+    >>> energies = [bands(k) for k in momenta]
+    >>> pyplot.plot(momenta, energies)
+    >>> pyplot.show()
     """
 
     def __init__(self, sys):

kwant/solvers/common.py

@@ -394,6 +394,11 @@ class SparseSolver(object):
         number, it returns a 2d NumPy array containing the wave function within
         the scattering region due to each mode of the given lead.  Index 0 is
         the mode number, index 1 is the orbital number.
+
+        Examples
+        --------
+        >>> wf = kwant.solvers.default.wave_func(some_sys, some_energy)
+        >>> wfs_of_lead_2 = wf(2)
         """
         return WaveFunc(self, sys, energy)