[Bro-Dev] Thoughts on documenting scripts
robin at icir.org
Tue Nov 23 13:40:29 PST 2010
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 Sommer * Phone +1 (510) 722-6541 * robin at icir.org
ICSI/LBNL * Fax +1 (510) 666-2956 * www.icir.org
More information about the bro-dev