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