Standard for documenting messages?

28 views
Skip to first unread message

Josh English

unread,
Apr 23, 2012, 12:52:58 PM4/23/12
to pypu...@googlegroups.com
I've returned to programming and using PubSub again, and I realize I don't know if I've seen a standard way of documenting the messages sent by various functions and methods.

Has anyone addressed this?

Currently, in my docstring, I am creating simple text tables before explaining the output:

"""...
    This function emits PubSub.Pub messages:
        TOPIC                      ARGS
        creating_debit             start (bool)
        creating_debit_information this (int)  total=number_of_reports (int)

    Returns the file name (either the first name-ID pair, or error.xls)
"""


Werner

unread,
Apr 23, 2012, 1:12:11 PM4/23/12
to pypu...@googlegroups.com
Hi Josh,


On 23/04/2012 18:52, Josh English wrote:
I've returned to programming and using PubSub again, and I realize I don't know if I've seen a standard way of documenting the messages sent by various functions and methods.

Has anyone addressed this?

Currently, in my docstring, I am creating simple text tables before explaining the output:

"""...
    This function emits PubSub.Pub messages:
        TOPIC                      ARGS
        creating_debit             start (bool)
        creating_debit_information this (int)  total=number_of_reports (int)

    Returns the file name (either the first name-ID pair, or error.xls)
"""
I use the latest pubsub (wxPython 2.9.3 or pubsub site) and use then have a topics definition like this:

class infoBar:
    """An InfoBar needs to be shown or hidden"""

    class showMsg:
        """
        :param `msg`: the msg to be shown
        :param `flag`: wx.ICON_something, it is assumed that the listening handler
            will default to wx.ICON_INFORMATION, depending on where the statusText
            is shown it could also ignore this flag (e.g. when using wx.StatusText)
        :param `view`: show only on this view   
   
        """
   
        def msgDataSpec(msg, flag=None, view=None):
            """params doc defined on class above"""

With this I get nice call completion on "pTopics.etc" and a call tips in WingIDE or other IDE's when cursor sits on "showMsg" with something like below.

    pub.sendMessage(pTopics.infoBar.showMsg, msg='message for statusText')

Werner

Werner

unread,
Apr 23, 2012, 1:17:04 PM4/23/12
to pypu...@googlegroups.com
In other words follow Sphinx/.rst standards which are nicely explained in the Phoenix Docstrings Guidelines.

http://xoomer.virgilio.it/infinity77/Phoenix/DocstringsGuidelines.html

Werner

oliver

unread,
Apr 24, 2012, 9:15:56 AM4/24/12
to pypu...@googlegroups.com
Josh, 
I highly recommend using the topic tree definition as this documents the message API (which is shared by every listener of a given message type), so you don't have to repeat the documentation for every listener. See Werner's reply, and there is example on the pubsub home pages (pubsub.sf.net). For instance the file kwargs_topics.py, and files in same folder for examples of using this. This is most powerful in the default messaging scheme (called kwargs) but will also work with "arg1" and "v1".
Oliver

--
You received this message because you are subscribed to the Google Groups "pypubsub" group.
To post to this group, send email to pypu...@googlegroups.com.
To unsubscribe from this group, send email to pypubsub+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pypubsub?hl=en.

Josh English

unread,
Apr 24, 2012, 10:59:51 AM4/24/12
to pypu...@googlegroups.com
Guys,

I think you're answering a different question.

I'm talking about in the docstrings for the functions I write in my own code. Good documentation requires an explanation of the input and output, but pubsub messages aren't necessarily either input or output. 

If someone were to load my code, and use the interpreter to type "help(my_function)", how would they know what pubsub messages are generated (or trigger) the function? I was wondering if there was a standard way. The formal documenting tools (I've been using Sphinx) don't have handy ways of doing this the way it can remark on parameters.

oliver

unread,
Apr 24, 2012, 11:40:00 AM4/24/12
to pypu...@googlegroups.com
There is no standard way, but here is what I would use:  
  • If my function generates pubsub messages, then docstring mentions the message name; and perhaps what data (members) it sends, but often the code is clear enough without this
  • If my function is a listener, then its doc string mentions which message type it will be subscribed to (and what happens when message handled), but refers to topic definition file for arg docs
With the above, the reader can refer to my topics definition .py file for listener/sendMessage parameters. I don't know of a way to make a listener "merge in" the docstring of a topic definition automatically but that would be ideal...

Is this what you were looking for? 

Oliver

Josh English

unread,
Apr 24, 2012, 1:13:14 PM4/24/12
to pypu...@googlegroups.com
Yeah. Thanks. I wish I were good enough to expand the documentation softwares to write a doc plug in for this sort of thing.
Reply all
Reply to author
Forward
0 new messages