Add more documentation to gracedb_events.py; update documentation elsewhere; fixes #25

This MR both addresses #25 (closed) by defining the relevant parameters, as well as updating the documentation in conjunction with !93 (merged)

ligo/raven/gracedb_events.py

@@ -38,7 +38,26 @@ from ligo.skymap.io import fits
 #######################################################
 
 class ExtTrig(object):
-    """ Instance of an external trigger event (e.g. gamma-ray burst) """
+    """ Instance of an external trigger event (e.g. gamma-ray burst)
+
+    Parameters
+    ----------
+    graceid: str
+        ID of the trigger used by GraceDB
+    gracedb: class
+        SDK or REST API client for HTTP connection
+    event_dict: dict
+        Dictionary of external event
+    fitsfile: str
+        External event's skymap file name
+    is_moc: bool
+        If True, assumes multi-order coverage (MOC) external event skymap
+    use_radec: bool
+        If True, use ra and dec for single pixel external skymap
+    nested: bool
+        If True, assumes external skymap uses nested ordering, otherwise
+        assumes ring ordering
+    """
     def __init__(self, graceid, gracedb=None, event_dict=None,
                  fitsfile=None, is_moc=True, use_radec=False, nested=True):
         self.is_gracedb_sdk = _is_gracedb_sdk(gracedb)
@@ -104,7 +123,18 @@ class ExtTrig(object):
 
     def submit_gracedb_log(self, message, filename=None, filecontents=None,
                            tags=[]):
-        """ Wrapper for gracedb.logs() for this event """
+        """ Upload log to GraceDB for this event
+
+        Parameters
+        ----------
+        message: str
+            Log message to upload
+        filename: class
+            Name of file to upload
+        filecontents: bytes
+            Contents of file to upload in bytes
+        tags: list
+            List of tags to include in log message"""
         if self.is_gracedb_sdk:
             self.gracedb.events[self.graceid].logs.create(
                 comment=message,
@@ -121,7 +151,24 @@ class ExtTrig(object):
 
 
 class SE(object):
-    """Instance of a superevent"""
+    """Instance of a superevent
+
+    Parameters
+    ----------
+    graceid: str
+        ID of the trigger used by GraceDB
+    gracedb: class
+        SDK or REST API client for HTTP connection
+    event_dict: dict
+        Dictionary of superevent
+    fitsfile: str
+        GW's skymap file name
+    is_moc: bool
+        If True, assumes multi-order coverage (MOC) GW skymap
+    nested: bool
+        If True, assumes GW skymap uses nested ordering, otherwise
+        assumes ring ordering
+    """
     def __init__(self, superevent_id, event_dict=None, gracedb=None,
                  fitsfile=None, is_moc=True, nested=True):
         self.is_gracedb_sdk = _is_gracedb_sdk(gracedb)
@@ -176,7 +223,18 @@ class SE(object):
 
     def submit_gracedb_log(self, message, filename=None, filecontents=None,
                            tags=[]):
-        """ Wrapper for gracedb.logs() for this event """
+        """ Upload log to GraceDB for this event
+
+        Parameters
+        ----------
+        message: str
+            Log message to upload
+        filename: class
+            Name of file to upload
+        filecontents: bytes
+            Contents of file to upload in bytes
+        tags: list
+            List of tags to include in log message"""
         if self.is_gracedb_sdk:
             self.gracedb.superevents[self.graceid].logs.create(
                 comment=message,