[Bro-Dev] Thoughts on documenting scripts

[Gregor Maier]

Hi,

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.


cu
gregor
-- 
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