[Tutor] doc string format ?

[Kent Johnson]

On Sun, Jun 8, 2008 at 4:54 AM, dave selby <dave6502 at googlemail.com> wrote:
> Hi All,
>
> I am trying to improve my code quality and have started using doc
> strings. What format do you guys use for your doc strings ?

PEP 257 has some general recommendations:
http://www.python.org/dev/peps/pep-0257/

The standard library has lots of examples.

> I have 'made up' the following general format ...

>    """
>    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:
>    """

If you are going to use a structured format you might consider a
format recognized by a documentation generator such as epydoc:
http://epydoc.sourceforge.net/
http://epydoc.sourceforge.net/relatedprojects.html

Kent