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
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".
There will at least be a number of things in bro.init declared in the global namespace that we really need to document, but I think you generally have it right. I'm trying to avoid anything in the global namespace as I work on the script rewrite though. The one exception is the notice.bro script because there is a well known function in the global namespace named NOTICE that is sort of the entry point for generating notices.
2) Are there any initial thoughts on whether the auto-generated documentation should even include the "private interface" stuff?
No, I wouldn't bother with it for this release. If it turns out that it's something that people would like to have then we can add it, but I don't expect there will be a huge demand for it.
.Seth
There will at least be a number of things in bro.init declared in the
global namespace that we really need to document
Yeah, that's exactly the stuff I found missing from my first run of auto-generated docs that I had in mind when asking the question.
> 2) Are there any initial thoughts on whether the auto-generated
> documentation should even include the "private interface" stuff?
No, I wouldn't bother with it for this release. If it turns out that
it's something that people would like to have then we can add it, but
I don't expect there will be a huge demand for it.
Good to know in case it turns out to be a mess to get that to work, but I'm thinking it might be simple.
It could probably even be an extra "verbose documentation" command line switch to bro that will create both the public and the private interface docs and then we can decide later if it's actually useful to provide.
- Jon