[Bro-Dev] first try at a skeleton script

Robin Sommer robin at icir.org
Sun Oct 17 21:36:48 PDT 2010


On Mon, Oct 04, 2010 at 14:08 -0700, Gregor Maier wrote:

> I'm just wondering whether not using markers might end up exploding in
> our faces once enough people write doc strings ....

"Exploding" in which sense?

(Note that I'm not too strong on not using markers; I personally
find them cumbersome, but I can also configure my editor to do it
for me :)

On Mon, Oct 04, 2010 at 14:20 -0700, Gregor Maier wrote:

> Is a user somebody who just needs to use the "interface" (globals,
> events, etc.) the script defines or somebody who might want to modify
> the script according to their needs.

I meant the former. I don't think we should formalize documenting a
script's internals. As Adam wrote, for that it's often easier to
read the source directly, and where it isn't, a few informal
comments (which don't go into the reference manual) are fine, just
as it's now. 

My point was a different one: Seth's initial skeleton had some
instructions for the person writing a script *initially* (e.g., how
to structure things etc.).  I found that confusing as there was no
separation between these and things which will be left in the final
script for people later needing to understand the interface.

> Or maybe the per-element doc-comments can have a flag indicating whether
> they are public interface or internal functionality. 

Can't we just use the export section? Everything in there is by
definition part of the interface and should be documented. 
 
> Maybe more general: can we come up with a nice way to document the redef
> of the various "special purpose" globals that are edited by many
> scripts? E.g., Notice enums, capture filters, analyzer configurations, etc.

Good point. For these we need two different types of documentation:
one defining the purpose of the global, and one which states how a
script modifies the global when loaded. However, there aren't that
many of these so we might be fine special-casing them (i.e., just
listing which notices, filters, etc. a script defines).

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