[Bro-Dev] Thoughts on documenting scripts

[Robin Sommer]

On Tue, Nov 23, 2010 at 10:21 -0800, you wrote:

> * However, also document the internal workings (which IMHO is good
>   style anyway)

It's good style but I'd prefer to leave it informal how to do that.
Enforcing consistent documentation of script internals increases the
burden on the scritp writer quite a bit, without that much benefit
actually (because often one will end up just reading the script code
anyway; there's no better documention then that.)

> * This raises the question of documenting generated events VS. event
>   handlers. I guess that bro should be able to distinguish them, since
>   the definition of policy-generated event is presumably followed by a
>   semicolon and no body while a handler always has a body, right?

The easier way would be to look for uses of the "event" statement;
that directly shows what events are raised. Independent of the
question whether to generate docs for internals, I can see
summarizing for which events a script has handlers, and which events
it generates. That's quite interesting information as it introduces
dependencies with other scripts. 

Robin

-- 
Robin Sommer * Phone +1 (510) 722-6541 * robin at icir.org
ICSI/LBNL    * Fax   +1 (510) 666-2956 *   www.icir.org