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
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
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
... and that would be another good option of doing it.
- Have you considered only using the namespace prefix
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(a)icir.org
ICSI/LBNL * Fax +1 (510) 666-2956 * www.icir.org