[Bro-Dev] first try at a skeleton script

[Gregor Maier]

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. 

ACK.

>     - 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. 

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

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

ACK.

>     - 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
USA