[Bro-Dev] Thoughts on documenting scripts
gregor at icir.org
Tue Nov 23 10:21:15 PST 2010
I've been thinking about documenting the public interface VS.
documenting everything. It might be helpful to have a cross referenced
documentation of everything if somebody wants to dig deeper.
How this the following sound to you:
* Per default only extract documentation for the public interface
(i.e., the export section plus some globals)
* However, also document the internal workings (which IMHO is good
* Have an option to extract and generate the full documentation. (We
probably won't ship this documentation, but people who want to hack
around in scripts can generate it for themselves)
* 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?
(Or could one define a policy-generated event with a header?)
If bro can make that distinction, then it should be able to separate
handlers from event definitions.
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