[Bro-Dev] first try at a skeleton script

Gregor Maier gregor at icir.org
Mon Oct 4 14:08:44 PDT 2010

On 9/29/10 15:27 , Robin Sommer wrote:
>     - As a general rule, I guess a comment block should always be
>     associated with the next language element. 


>     - The script itslef should start with a block describing the
>     overall purpose of the script and perhaps potential
>     caveats/things to keep in mind etc. 

Question: how to distinguish scripts' doc section from the doc section
of the first language element, if somebody choose to only use one of

>     - Each indidivual doc section should start with a single short
>     sentence summarizing the documented element, followed by further
>     text going into more detail. 


>     - Generally, all doc text is formatted in reST. However, one
>     thing I always hate when writing documentation strings is adding
>     all kinds of markers for things like parameters, return values,
>     etc. (e.g., "@param", or ":param:"). 
> [cut]
>      - "Returns: texttextext" is the magic to mark the description
>      of the return value. 

> Thoughts?

I'm just wondering whether not using markers might end up exploding in
our faces once enough people write doc strings ....

Gregor Maier                                             gregor at icir.org
Int. Computer Science Institute (ICSI)          gregor at icsi.berkeley.edu
1947 Center St., Ste. 600                    http://www.icir.org/gregor/
Berkeley, CA 94704

More information about the bro-dev mailing list