- The "private interface" section is still tracked, but no longer rendered.
We can judge the usefulness of it later and add back if there's demand.
- Documentation of event handlers was being treated the same as event
declarations. Now handlers are tracked separately, but not currently
rendered in the generated doc output since usefulness is questionable.
- Fixing the parts of the `make restdoc` and `make doc` process that were
broken by the last Bro script re-organization
- Generated documentation for Bro scripts derived from BiFs now use the
original BiF source file as the "original source file" link
- Renaming of the internal POLICYDEST definition and other misc places that
refer to "policy" scripts; that terminology doesn't make total sense now
- Added a documentation blacklist reminder test that will fail if there's
scripts that are blacklisted from being documentated because they're still
in progress
- Some minor Bro script changes to fix small @load dependency errors
Addresses #543
* remotes/origin/topic/policy-scripts-new:
Add RPC/SSL scripts to doc generation target.
Update the generated script doc organization.
Changing back the last commit. It made things worse.
Trying a different method of record parsing for SSL analyzer.
Moved the RPC script into the right place.
More SSL script cleanup.
Fixed a segfault from empty strings in the SSL analyzer.
Removing what I believe is the last stray print statement from the SSL analyzer.
Fixed more eternal looping bugs in the SSL analyzer.
Updates and fixes for the SSL analyzer.
Changes to make generated script docs understand new policy/ hierarchy.
Added an arg to the search_for_files() util function that can return
the subpath of BROPATH's policy/ dir in which the loaded file is found.
This subpath is then used in both the the reST file's document title
(so that script's named e.g. "base.bro" actually have some context) and
in figuring out how to interlink with other generated docs of other
scripts that are found in @load directives.
I still need to overhaul things so the loading of "packages" is
documented in a meaningful way and that the CMake targets are able
to generate indexes for packages.
* remotes/origin/topic/policy-scripts-new: (264 commits)
Update core.vlan-mpls baseline.
Update core.conn-uid test/baseline.
Fixing tests / updating baselines.
Renaming a poorly named notice.
Resolving a conflict in scan.l.
Notice framework updates.
Fixed bug I just introduced to known-services.
Known services now only logs for "normal" connections.
Fix the name of the DPD log.
Updating the netstats script to match the new internal code.
Removed expected_connection_timeout variable.
New default notice actions for emailing network admins.
New default notice action for emailing network admins.
weird.bro moved into notice framework.
Removed a redundant and out of place mozilla CA list.
Renamed the stream for the notice log.
Small consistency tweaks for the communications framework.
Finishing the inactivity script.
Intel framework test passes now.
Reorganized some of the tests for consistency.
...
The output reST filename now reflects the subdir information (by flattening
'/' path separators into the '^' character). This is to prevent file name
conflicts when generated reST docs, but during the CMake 'doc' target to
build HTML docs, everything gets unflattened.
A function prototype can be declared separately from where it's defined;
the doc framework should now recognize them as the same and combine
reST documentation associated with either case if both are present.
A script's public API wasn't simply definable as identifiers
for which ID::IsGlobal() is true, e.g. an unexported identifier with
SCOPE_MODULE will still pass that test and (incorrectly) be considered
public API.
Also, generated reST now omits empty interface sections.
A bro script's public interface is taken to mean any identifier declared
in the global scope that optionally is exported from some namespace/module.
Or more simply: ID::IsGlobal()
This functionality is better done manually by the script writer
embedding reST into the script summary section (##! comments).
This allows flexibility in choosing between different methods
to convey the same information (e.g. ":Author: <author>" or
the ".. codeauthor:: <author>" directive that Sphinx
configurations can recognize).
It's allowed for a script to "@load example.bro", but Sphinx doesn't want
that file extension for the purposes of generating cross-referencing links
to other documentation.
This adds a new subclass of EnumType, CommentedEnumType, and removes
any previous changes to EnumType that were done to support the
autodoc framework.
Dummy CommentedEnumType and ID's are constructed in parallel with the
real EnumType ID's during parsing and passed on to the autodoc framework.
This allows the generated documentation to track enum redefs, with
a special case being the "Notice" enum type.
* New bro runtime options: -Z or --doc-scripts enables documentation mode
* New BroDoc, BroBifDoc, and BroDocObj interfaces to support script
documentation
* Modifications to the bro scanner (scan.l) to get it to keep track of
which script is being scanned/parsed and which document is being generated
* Modifications to scan.l and the bro parser (parse.y) to produce/consume
script comments denoted with "##"
* Documentation is currently generated for the following
** Script author
** Script summary
** @load's
** capture_filters
** modules (namespaces)
Most of the remaining framework/infrastructure work should be in extracting
the interesting BroObj objects as the parser sees them and better formatting
the reST documents.
