Merge pull request #316 from djarecka/doc_upd

[doc] updating the docstrings for messenger and audit

Author: djarecka

pydra/engine/audit.py

@@ -18,12 +18,13 @@ def __init__(self, audit_flags, messengers, messenger_args, develop=None):
         ----------
         audit_flags : :class:`AuditFlag`
             Base configuration of auditing.
-        messengers :
-            TODO
-        messenger_args :
-            TODO
-        develop :
-            TODO
+        messengers : :obj:`pydra.util.messenger.Messenger` or list of :class:`pydra.util.messenger.Messenger`, optional
+            Specify types of messenger used by Audit to send a message.
+            Could be `PrintMessenger`, `FileMessenger`, or `RemoteRESTMessenger`.
+        messenger_args : :obj:`dict`, optional
+            Optional arguments for the `Messenger.send` method.
+        develop : :obj:`bool`, optional
+            If True, the local context.jsonld file is used, otherwise the one from github is used.
 
         """
         self.audit_flags = audit_flags
@@ -115,10 +116,10 @@ def audit_message(self, message, flags=None):
 
         Parameters
         ----------
-        message :
-            TODO
-        flags :
-            TODO
+        message : :obj:`dict`
+            A message in Pydra is a JSON-LD message object.
+        flags : :obj:`bool`, optional
+            If True and self.audit_flag, the message is sent.
 
         """
         if self.develop:
@@ -149,8 +150,12 @@ def audit_check(self, flag):
 
         Parameters
         ----------
-        flag :
-            TODO
+        flag : :obj: `bool`
+            The flag that is checked.
 
+        Returns
+        -------
+        bool
+            Boolean AND for self.oudit_flags and flag
         """
         return self.audit_flags & flag

pydra/utils/messenger.py

@@ -56,7 +56,7 @@ class PrintMessenger(Messenger):
 
     def send(self, message, **kwargs):
         """
-        Send to standard output.
+        Send the message to standard output.
 
         Parameters
         ----------
@@ -88,6 +88,10 @@ def send(self, message, append=True, **kwargs):
         append : :obj:`bool`
             Do not truncate file when opening (i.e. append to it).
 
+        Returns
+        -------
+        str
+            Returns the unique identifier used in the file's name.
         """
         import json
 
@@ -114,6 +118,11 @@ def send(self, message, **kwargs):
         message : :obj:`dict`
             The message to be printed.
 
+        Returns
+        -------
+        int
+            The status code from the `request.post`
+
         """
         import requests
 
@@ -134,7 +143,21 @@ def send_message(message, messengers=None, **kwargs):
 
 
 def make_message(obj, context=None):
-    """Build a message."""
+    """
+    Build a message using the specific context
+
+    Parameters
+    ----------
+    obj : :obj:`dict`
+        A dictionary containing the non-context information of a message record.
+    context : :obj:`dict`, optional
+        Dictionary with the link to the context file or containing a JSON-LD context.
+
+    Returns
+    -------
+    dict
+        The message with the context.
+    """
     if context is None:
         context = {
             "@context": "https://raw.githubusercontent.com/nipype/pydra/master/pydra/schema/context.jsonld"
@@ -145,7 +168,19 @@ def make_message(obj, context=None):
 
 
 def collect_messages(collected_path, message_path, ld_op="compact"):
-    """Gather messages."""
+    """
+    Compile all messages into a single provenance graph.
+
+    Parameters
+    ----------
+    collected_path : :obj:`os.pathlike`
+        A place to write all of the collected messages. (?TODO)
+    message_path : :obj:`os.pathlike`
+        A path with the message file (?TODO)
+    ld_op : :obj:`str`, optional
+        Option used by pld.jsonld
+    """
+
     import pyld as pld
     import json
     from glob import glob