[Bro-Dev] first try at a skeleton script

[Gregor Maier]

> - The explanatory text is very helpful when writing a script,
> however we should make it clear that once a script is done, this
> should be removed, as otherwise we'll end up with many scripts
> having the same boilerplate in them. So, perhaps it makes sense to
> start anything that's just explaining something with an explicit
> marker, like
> 
>     # REMOVE-ME: The export section contains the external ...
>     # REMOVE-ME: ......
> 
> - Also, some elements have a documentation string (i.e., something
> that will end up in the auto-generated documentation later) while
> others don't. I think that generally at least everything in the
> export section should have documentation. 


> - Taking the two previous points together, it doesn't yet become
> clear what is documentation for a script's *users*, vs. what is help
> for a script *writer*.

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 guess the question is: where do we draw the line? Maybe it would help
if the per-script doc-block would specify the "public" interface that
users have to know about.....

Or maybe the per-element doc-comments can have a flag indicating whether
they are public interface or internal functionality. Then the doc
generator can separate these elements for the output. Then a user can
quickly see, what's relevant (which events, functions, globals) and
somebody who needs to understand the script (to enhance, modify,
whatever) also has all the information.

> - As an alternative, we could keep the writer help inside a script
> to a minimum, but have an additional external document giving more
> details. Not sure which approach is better. 

I think that everything that documents the actual script should go into
the script. If we separate code from documentation, we will probably
face the problem that the documentation and the code don't match further
down the road. Documentation about language elements can maybe go into a
different document.


> - The Notice enums should be documented as well. 

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.


cu
gregor

-- 
Gregor Maier                                             gregor at icir.org
Int. Computer Science Institute (ICSI)          gregor at icsi.berkeley.edu
1947 Center St., Ste. 600                    http://www.icir.org/gregor/
Berkeley, CA 94704
USA