[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