[Tutor] doc string format ?

[wesley chun]

> I am trying to improve my code quality and have started using doc
> strings. What format do you guys use for your doc strings ?
> I have 'made up' the following general format ...
>
> def gen_vhost(kmotion_dir):
>    """
>    Generate the kmotion vhost file from vhost_template expanding %directory%
>    strings to their full paths as defined in kmotion.rc
>
>    arguments :
>    kmotion_dir ... the 'root' directory of kmotion
>
>    exceptions:
>    exit ... if kmotion.rc cannot be read
>
>    returns:
>    """


dave,

excellent question and good to see that "you care" enough to ask.
docstrings are one of Python's strengths, esp. given some of the
external tools that are at your disposal.

a) my 1st suggestion is to add some code to any of your docstrings
where it makes sense; and even better would be some output.  for
example:

def foo(x):
    """foo(x): display argument 'x'

        >>> foo(123)
        123
    """
    print x

this is helpful because if you're writing code for others (including
yourself), it's easy to see what the proper syntax/usage is.

b) given the above, wouldn't it be neat if there was a tool that could
actually *execute* that code in your docstring as a regression test to
(help) ensure code correctness? well, there is, and it's called the
doctest module.  if you add in the snippet below, you've just added
testing for your code (and docstring)!

def _test():
    import doctest
    doctest.testmod()

if __name__ == '__main__':
    _test()

when you run your program, it should give no output if things ran
swimmingly. if you do get output, that means that something went
wrong.  to see that it really works, just run your code with a "-v"
flag:

$ foo.py -v
Trying:
    foo(123)
Expecting:
    123
ok
3 items had no tests:
    __main__
    __main__.User
    __main__._test
1 items passed all tests:
   1 tests in __main__.foo
1 tests in 4 items.
1 passed and 0 failed.
Test passed.
-----

the output tells you that of the 4 places that docstrings could go,
only 1 had a test in a docstring (the other 3 didn't).

c) on top of this, i would also 2nd kent's suggestion of using Epydoc,
which is also compatible with doctest docstrings:
http://epydoc.sourceforge.net/manual-epytext.html

adding a bit more, you get this:

def foo(x):
    """foo(x): display argument 'x'

        >>> foo(123)
        123

        @param x: this is the main arg for foo()
        @type x: 'x' can be any object, i.e., int, str, etc.
        @return: None since there is no explicit return
    """
    print x

now you can use Epydoc to generate HTML or PDF documentation of your
entire code base!

hope this helps!
-- wesley
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
"Core Python Programming", Prentice Hall, (c)2007,2001
 http://corepython.com

wesley.j.chun :: wescpy-at-gmail.com
python training and technical consulting
cyberweb.consulting : silicon valley, ca
http://cyberwebconsulting.com