[Bro-Dev] bro script "public interface"

[Jonathan Siwek]

WRT my work on auto-generation of script documentation...

I'm taking a bro script's "public interface" to mean:

any identifier declared in the GLOBAL namespace/module (regardless of whether it's in an export section)
OR
any identifier declared in an export section for a namespace/module other than GLOBAL

from that, it follows that "private interface" is:

any identifier declared outside an export section AND not in the GLOBAL namespace/module

Aside from commenting on the correctness of those definitions:

1) Is this in line with the way standard scripts are being "modernized" ? I think a big part of it involves updating them to use the namespacing capabilities, but I think there's still desire to declare some things in the GLOBAL namespace?  That's why I'm still considering that situation as part of the script's "public interface".

2) Are there any initial thoughts on whether the auto-generated documentation should even include the "private interface" stuff?  Since "private" things are accessible only from within the given script, it's implied that the person who is interested in that stuff is one who is actually working on modifying the script itself and they could easily rely on the old-fashioned script comments for documentation.  On the other hand, the "private" stuff could be utilizing the "public" stuff of other scripts and the auto-generated docs might provide more convenient cross-references for that.

- Jon