docs(surfinfo): add missing docstring for flat_border

cortex/surfinfo.py

@@ -153,6 +153,22 @@ def tissots_indicatrix(outfile, sub, radius=10, spacing=50):
     np.savez(outfile, left=tissots[0], right=tissots[1], centers=allcenters)
 
 def flat_border(outfile, subject):
+    """
+    Compute the boundary of the flatmap as a set of line segments, split into
+    segments that lie along the medial wall and segments that don't, and
+    save the result to `outfile`.
+
+    Parameters
+    ----------
+    outfile : str
+        Path where the border map will be saved as an npz file, with `lines`
+        (a list of boundary line segments, each an array of 2D points) and
+        `ismwalls` (a boolean flag for each segment indicating whether it
+        lies along the medial wall) arrays.
+    subject : str
+        Subject in the pycortex database for whom the flatmap border will be
+        computed.
+    """
     flatpts, flatpolys = db.get_surf(subject, "flat", merge=True, nudge=True)
     flatpolyset = set([tuple(x) for x in flatpolys])
 
@@ -200,7 +216,11 @@ def make_surface_graph(tris):
         splitbounds.append(sb)
 
     ismwall = [[s.mean()>0.5 for s in np.split(mwb, c)] for mwb,c in zip(mwallbounds, changes)]
-
+
+    # FIXME: `height` is undefined -- this raises NameError as written.
+    # It was presumably meant to be a parameter (see the commented-out
+    # Image.new(...) call below, which used it as the output image height
+    # in pixels). Needs a reviewer decision on the right fix/default.
     aspect = (height / (flatpts.max(0) - flatpts.min(0))[1])
     lpts = (flatpts - flatpts.min(0)) * aspect
     rpts = (flatpts - flatpts.min(0)) * aspect