[Bro-Dev] Thoughts on documenting scripts

Robin Sommer robin at icir.org
Tue Nov 23 09:44:49 PST 2010

On Mon, Nov 22, 2010 at 19:59 -0800, you wrote:

> - How do you define a Public Interface?

I'm thinking whatever the "export section" provides. The earlier
sections are things the script configures, but they are part of
*another* script's interface. 

> - 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?

This is not for DPD, but for the port-based detection. The
interpretation is: everything on port 21 will always be analyzed as
FTP (while all other ports need a matching DPD pattern first).

But there are probably nicer ways of phrasing this in the generated
documentation that in my example. 

> - 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.

Yes, that's the plan. Everything would be extensively cross-linked,
and in this case the link would go to bro.init's apge (which is a
special case however, which we'll probably need to handle separately
in some form).

> - I feels a bit too much to repeat the word Param in front of every
>   event parameter.

I totally agree. I had earlier suggested to do this implicitly,
e.g., instead of ":param id: bla bla", write just "id: bla bla" and
do some smart pattern matching to recognize that it's actually a
parameter description.

I'm still in favor of doing that but didn't want to load too many
details onto the proposal.

> What about writing 'Parameters' once and then listing all parameters
> in bullet-point style (or just as is, in bold and then the
> description).

... and that would be another good option of doing it. 

> - 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?

Yeah, I was unsure what's the best way for giving the namespaces.
This could be indeed a good compromise. 

> - 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.

I like that. However, Sphinx doesn't provide that directly so we'd
need to assemble that information somehow (should be possible)


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 mailing list