[Bro-Dev] Thoughts on documenting scripts

[Matthias Vallentin]

> What do you guys think?

Very nice, I like the overall setup, it looks like a smooth way to
automate the documentation generation process for Bro scripts! A few
comments:

- How do you define a Public Interface? It seems to me that the sections
  before are also customizable by the user and thus constitute part of
  the "public" part of the script.

- The role of DPD is not entirely clear from the HTML in the sections
  Packet Filter and Port Analysis. It reads as if FTP is only invoked
  for 21/tcp. How is that supposed to be read?

- I am not sure if this would happen already, but it would be great if
  external types, such as the connection record, would also be links in
  the HTML generated by Sphinx.

- I feels a bit too much to repeat the word Param in front of every
  event parameter. What about writing 'Parameters' once and then listing
  all parameters in bullet-point style (or just as is, in bold and then
  the description). 

- Have you considered only using the namespace prefix (FTP::) for
  handlers that are not part of the module and omitting it for functions
  and events that are inside the module? 

- In addition to the included children, it would also be nice to create
  a list of parents, i.e., the scripts that include the script whose
  documentation is currently being read.

   Matthias