add some mangle documentation

pydl/pydlutils/mangle/read_fits_polygons.py

@@ -6,16 +6,25 @@ def read_fits_polygons(filename):
     The main point of this is to extract the xcaps and cmcaps columns
     and replace them with caps.x and caps.cm, though this is really very silly
     & is only here so it's similar to IDL.
+
+    Parameters
+    ----------
+    filename : str
+        Name of FITS file to read.
+
+    Returns
+    -------
+    read_fits_polygons : FITS_rec
+        The data contained in HDU 1 of the FITS file.
     """
     from astropy.io import fits
     hdulist = fits.open(filename)
     poly = hdulist[1].data
     hdulist.close()
-    #poly['CAPS'] = {'CM':list(), 'X':list()}
-    #for k in range(len(poly['NCAPS'])):
-    #    poly['CAPS']['CM'].append(poly['CMCAPS'][k,0:poly['NCAPS'][k]])
-    #    poly['CAPS']['X'].append(poly['XCAPS'][k].reshape((8,3))[0:poly['NCAPS'][k]])
-    #del poly['CMCAPS']
-    #del poly['XCAPS']
+    # poly['CAPS'] = {'CM':list(), 'X':list()}
+    # for k in range(len(poly['NCAPS'])):
+    #     poly['CAPS']['CM'].append(poly['CMCAPS'][k,0:poly['NCAPS'][k]])
+    #     poly['CAPS']['X'].append(poly['XCAPS'][k].reshape((8,3))[0:poly['NCAPS'][k]])
+    # del poly['CMCAPS']
+    # del poly['XCAPS']
     return poly
-

pydl/pydlutils/mangle/set_use_caps.py

@@ -13,17 +13,28 @@ def set_use_caps(x,cm,polygon_use_caps,add=False,tol=1.0e-10,allow_doubles=False
 
     Parameters
     ----------
-    x
-    cm
-    polygon_use_caps
-    add
-    tol
-    allow_doubles
-    allow_neg_doubles
+    x : array-like
+        Polygon `x` value.
+    cm : array-like
+        Polygon `cm` value.
+    polygon_use_caps : int
+        Input value of use_caps.
+    add : bool, optional
+        If ``True``, don't initialize the use_caps value to zero, use the value of
+        `polygon_use_caps` instead.
+    tol : float, optional
+        Tolerance used to determine whether two caps are identical.
+    allow_doubles : bool, optional
+        Normally, this routine automatically sets use_caps such that no
+        two caps with use_caps set are identical.
+    allow_neg_doubles : bool, optional
+        Normally, two caps that are identical except for the sign of `cm`
+        would be set unused.  This inhibits that behaviour.
 
     Returns
     -------
-
+    set_use_caps : long
+        Value of use_caps.
     """
     import numpy as np
     from . import is_cap_used
@@ -49,4 +60,3 @@ def set_use_caps(x,cm,polygon_use_caps,add=False,tol=1.0e-10,allow_doubles=False
                                 #
                                 use_caps -= long(2)**j
     return use_caps
-