- Fix examples/references in the file analysis how-to/usage doc.
- Add Broxygen-generated docs for file analyzer plugins.
- Break FTP::Info type declaration out in to its own file to get
rid of some circular dependencies (between s/b/p/ftp/main and
s/b/p/ftp/utils).
* master-merge-helper:
possible use after free forbidden
Suppression of unused code
Fix of some memory leaks
removing dead code
A destructor must free the memory allocated by the constructor
Good overridance with the good qualifier
Better use of operators priorities
protection from bad frees on unallocated strings
Includes:
- Quite a bit of CSS tweaking.
- Some small changes to BroDoc.cc to change the order of sections.
- A bit of tweaking some reST here and there.
- 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 some Metrics::add_data() call signatures
- slight refactors to cluster framework @if and adding a NONE NodeType for
so local_node_type() will return that instead of just emitting an error
when cluster mode isn't enabled
- `make restdoc` target now uses bro's bare-mode
- bro scripts generated from bifs now really only live in the build/src/base/
directory and changed the DocSourcesList.cmake to dynamically figure out
what bifs exist by looking in src/ instead of build/src/
- add some missing @load dependencies
- 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 additional master TOC index for Bro script packages that
automatically gets filled in at ``make doc`` time. The master TOC
links to per-package indexes which contains links to all the scripts
contained within it along with their summary. The per-package index
is also now automatically generated/derived from the path component
of the script passed into the rest_target() macro.
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.
* remotes/origin/topic/jsiwek/doc-framework:
Adding example documentation for a script's use of logging features.
Adding &log attribute to static attr_names array.
Small typo fix.
Bro doc mode now tracks record redefs that extend its field list.
BroBifDoc was unneeded; now dead code, so removed.
Bro doc mode now only does a "shallow" copy of declared record types
Bro's doc mode now terminates after processing bro_init but before net_run
Fixes related to `make doc` handling of script summary text (##! comments)
Overhaul of "doc" build target for generating policy script documentation.
Add parser error hint when in doc mode about checking ## comment syntax.
Move stuff related to policy script documentation from doc/ to doc/scripts/
Fixing example.bro's auto-reST generation baseline test.
It's now all implemented in CMake scripting.
The generation of reST docs is now a distinct target, "restdoc", while
the target to generate HTML docs, "doc", depends on "restdoc". reST doc
generation supports incremental builds (documentation for a given policy
script is only regenerated when it is out of date), but HTML doc generation
via ``make doc`` is not incremental (Sphinx always starts with fresh input).
Building the "restdoc" target is now covered by a btest to ensure all
policy scripts are parse-able when Bro is in "doc mode".
Generated reST docs should now support "@load"ing from subdirectories. e.g.
"@load foo/baz" and "@load bar/baz" will now generate the right xref links.
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.
They now appear at the bottom of generated docs.
Also, a "more info" link is added which can point to an arbitrary location
in any reST document processed by Sphinx.
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.
And (to be consistent with current conventions for reST documentation)
update places in the auto-documentation-generation framework
where tabs were used in the generated reST.
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.
