[Bro-Dev] Thoughts on documenting scripts

Gregor Maier 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
  style anyway)
* 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 mailing list