mirror of
https://github.com/zeek/zeek.git
synced 2025-10-13 12:08:20 +00:00
fe5f4b8e53
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.
348 lines
9.3 KiB
ReStructuredText
348 lines
9.3 KiB
ReStructuredText
.. Automatically generated. Do not edit.
|
|
|
|
example.bro
|
|
===========
|
|
|
|
:download:`Original Source File <example.bro>`
|
|
|
|
Overview
|
|
--------
|
|
This is an example script that demonstrates how to document. Comments
|
|
of the form ``##!`` are for the script summary. The contents of
|
|
these comments are transferred directly into the auto-generated
|
|
`reStructuredText <http://docutils.sourceforge.net/rst.html>`_
|
|
(reST) document's summary section.
|
|
|
|
.. tip:: You can embed directives and roles within ``##``-stylized comments.
|
|
|
|
A script's logging information has to be documented manually as minimally
|
|
shown below. Note that references may not always be possible (e.g.
|
|
anonymous filter functions) and a script may not need to document
|
|
each of "columns", "event", "filter" depending on exactly what it's doing.
|
|
|
|
**Logging Stream ID:** :bro:enum:`Example::EXAMPLE`
|
|
:Columns: :bro:type:`Example::Info`
|
|
:Event: :bro:id:`Example::log_example`
|
|
:Filter: ``example-filter``
|
|
uses :bro:id:`Example::filter_func` to determine whether to
|
|
exclude the ``ts`` field
|
|
|
|
:Author: Jon Siwek <jsiwek@ncsa.illinois.edu>
|
|
|
|
:Imports: :doc:`frameworks/notice/index </policy/frameworks/notice/index>`
|
|
|
|
Summary
|
|
~~~~~~~
|
|
Options
|
|
#######
|
|
============================================================================ ======================================
|
|
:bro:id:`Example::an_option`: :bro:type:`set` :bro:attr:`&redef` add documentation for "an_option" here
|
|
|
|
:bro:id:`Example::option_with_init`: :bro:type:`interval` :bro:attr:`&redef`
|
|
============================================================================ ======================================
|
|
|
|
State Variables
|
|
###############
|
|
=========================================================================== =======================================
|
|
:bro:id:`Example::a_var`: :bro:type:`bool` put some documentation for "a_var" here
|
|
|
|
:bro:id:`Example::var_with_attr`: :bro:type:`count` :bro:attr:`&persistent`
|
|
|
|
:bro:id:`Example::var_without_explicit_type`: :bro:type:`string`
|
|
=========================================================================== =======================================
|
|
|
|
Types
|
|
#####
|
|
====================================================== ==========================================================
|
|
:bro:type:`Example::SimpleEnum`: :bro:type:`enum` documentation for "SimpleEnum"
|
|
goes here.
|
|
|
|
:bro:type:`Example::SimpleRecord`: :bro:type:`record` general documentation for a type "SimpleRecord"
|
|
goes here.
|
|
|
|
:bro:type:`Example::ComplexRecord`: :bro:type:`record` general documentation for a type "ComplexRecord" goes here
|
|
|
|
:bro:type:`Example::Info`: :bro:type:`record` An example record to be used with a logging stream.
|
|
====================================================== ==========================================================
|
|
|
|
Events
|
|
######
|
|
================================================= =============================================================
|
|
:bro:id:`Example::an_event`: :bro:type:`event` Summarize "an_event" here.
|
|
|
|
:bro:id:`Example::log_example`: :bro:type:`event` This is a declaration of an example event that can be used in
|
|
logging streams and is raised once for each log entry.
|
|
|
|
:bro:id:`bro_init`: :bro:type:`event`
|
|
================================================= =============================================================
|
|
|
|
Functions
|
|
#########
|
|
=============================================== =======================================
|
|
:bro:id:`Example::a_function`: :bro:type:`func` Summarize purpose of "a_function" here.
|
|
=============================================== =======================================
|
|
|
|
Redefinitions
|
|
#############
|
|
===================================================== ========================================
|
|
:bro:type:`Log::ID`: :bro:type:`enum`
|
|
|
|
:bro:type:`Example::SimpleEnum`: :bro:type:`enum` document the "SimpleEnum" redef here
|
|
|
|
:bro:type:`Example::SimpleRecord`: :bro:type:`record` document the record extension redef here
|
|
===================================================== ========================================
|
|
|
|
Namespaces
|
|
~~~~~~~~~~
|
|
.. bro:namespace:: Example
|
|
|
|
Notices
|
|
~~~~~~~
|
|
:bro:type:`Notice::Type`
|
|
|
|
:Type: :bro:type:`enum`
|
|
|
|
.. bro:enum:: Example::Notice_One Notice::Type
|
|
|
|
any number of this type of comment
|
|
will document "Notice_One"
|
|
|
|
.. bro:enum:: Example::Notice_Two Notice::Type
|
|
|
|
any number of this type of comment
|
|
will document "Notice_Two"
|
|
|
|
.. bro:enum:: Example::Notice_Three Notice::Type
|
|
|
|
.. bro:enum:: Example::Notice_Four Notice::Type
|
|
|
|
Public Interface
|
|
----------------
|
|
Options
|
|
~~~~~~~
|
|
.. bro:id:: Example::an_option
|
|
|
|
:Type: :bro:type:`set` [:bro:type:`addr`, :bro:type:`addr`, :bro:type:`string`]
|
|
:Attributes: :bro:attr:`&redef`
|
|
:Default: ``{}``
|
|
|
|
add documentation for "an_option" here
|
|
|
|
.. bro:id:: Example::option_with_init
|
|
|
|
:Type: :bro:type:`interval`
|
|
:Attributes: :bro:attr:`&redef`
|
|
:Default: ``10.0 msecs``
|
|
|
|
State Variables
|
|
~~~~~~~~~~~~~~~
|
|
.. bro:id:: Example::a_var
|
|
|
|
:Type: :bro:type:`bool`
|
|
|
|
put some documentation for "a_var" here
|
|
|
|
.. bro:id:: Example::var_with_attr
|
|
|
|
:Type: :bro:type:`count`
|
|
:Attributes: :bro:attr:`&persistent`
|
|
|
|
.. bro:id:: Example::var_without_explicit_type
|
|
|
|
:Type: :bro:type:`string`
|
|
:Default: ``"this works"``
|
|
|
|
Types
|
|
~~~~~
|
|
.. bro:type:: Example::SimpleEnum
|
|
|
|
:Type: :bro:type:`enum`
|
|
|
|
.. bro:enum:: Example::ONE Example::SimpleEnum
|
|
|
|
and more specific info for "ONE"
|
|
can span multiple lines
|
|
|
|
.. bro:enum:: Example::TWO Example::SimpleEnum
|
|
|
|
or more info like this for "TWO"
|
|
can span multiple lines
|
|
|
|
.. bro:enum:: Example::THREE Example::SimpleEnum
|
|
|
|
documentation for "SimpleEnum"
|
|
goes here.
|
|
|
|
.. bro:type:: Example::SimpleRecord
|
|
|
|
:Type: :bro:type:`record`
|
|
|
|
field1: :bro:type:`count`
|
|
counts something
|
|
|
|
field2: :bro:type:`bool`
|
|
toggles something
|
|
|
|
general documentation for a type "SimpleRecord"
|
|
goes here.
|
|
|
|
.. bro:type:: Example::ComplexRecord
|
|
|
|
:Type: :bro:type:`record`
|
|
|
|
field1: :bro:type:`count`
|
|
counts something
|
|
|
|
field2: :bro:type:`bool`
|
|
toggles something
|
|
|
|
field3: :bro:type:`Example::SimpleRecord`
|
|
|
|
msg: :bro:type:`string` :bro:attr:`&default` = ``"blah"`` :bro:attr:`&optional`
|
|
attributes are self-documenting
|
|
|
|
general documentation for a type "ComplexRecord" goes here
|
|
|
|
.. bro:type:: Example::Info
|
|
|
|
:Type: :bro:type:`record`
|
|
|
|
ts: :bro:type:`time` :bro:attr:`&log`
|
|
|
|
uid: :bro:type:`string` :bro:attr:`&log`
|
|
|
|
status: :bro:type:`count` :bro:attr:`&log` :bro:attr:`&optional`
|
|
|
|
An example record to be used with a logging stream.
|
|
|
|
Events
|
|
~~~~~~
|
|
.. bro:id:: Example::an_event
|
|
|
|
:Type: :bro:type:`event` (name: :bro:type:`string`)
|
|
|
|
Summarize "an_event" here.
|
|
Give more details about "an_event" here.
|
|
|
|
:param name: describe the argument here
|
|
|
|
.. bro:id:: Example::log_example
|
|
|
|
:Type: :bro:type:`event` (rec: :bro:type:`Example::Info`)
|
|
|
|
This is a declaration of an example event that can be used in
|
|
logging streams and is raised once for each log entry.
|
|
|
|
.. bro:id:: bro_init
|
|
|
|
:Type: :bro:type:`event` ()
|
|
|
|
Functions
|
|
~~~~~~~~~
|
|
.. bro:id:: Example::a_function
|
|
|
|
:Type: :bro:type:`function` (tag: :bro:type:`string`, msg: :bro:type:`string`) : :bro:type:`string`
|
|
|
|
Summarize purpose of "a_function" here.
|
|
Give more details about "a_function" here.
|
|
Separating the documentation of the params/return values with
|
|
empty comments is optional, but improves readability of script.
|
|
|
|
|
|
:param tag: function arguments can be described
|
|
like this
|
|
|
|
:param msg: another param
|
|
|
|
|
|
:returns: describe the return type here
|
|
|
|
Redefinitions
|
|
~~~~~~~~~~~~~
|
|
:bro:type:`Log::ID`
|
|
|
|
:Type: :bro:type:`enum`
|
|
|
|
.. bro:enum:: Example::EXAMPLE Log::ID
|
|
|
|
:bro:type:`Example::SimpleEnum`
|
|
|
|
:Type: :bro:type:`enum`
|
|
|
|
.. bro:enum:: Example::FOUR Example::SimpleEnum
|
|
|
|
and some documentation for "FOUR"
|
|
|
|
.. bro:enum:: Example::FIVE Example::SimpleEnum
|
|
|
|
also "FIVE" for good measure
|
|
|
|
document the "SimpleEnum" redef here
|
|
|
|
:bro:type:`Example::SimpleRecord`
|
|
|
|
:Type: :bro:type:`record`
|
|
|
|
field_ext: :bro:type:`string` :bro:attr:`&optional`
|
|
document the extending field here
|
|
(or here)
|
|
|
|
document the record extension redef here
|
|
|
|
Port Analysis
|
|
-------------
|
|
:ref:`More Information <common_port_analysis_doc>`
|
|
|
|
SSL::
|
|
|
|
[ports={
|
|
443/tcp,
|
|
562/tcp
|
|
}]
|
|
|
|
Packet Filter
|
|
-------------
|
|
:ref:`More Information <common_packet_filter_doc>`
|
|
|
|
Filters added::
|
|
|
|
[ssl] = tcp port 443,
|
|
[nntps] = tcp port 562
|
|
|
|
Private Interface
|
|
-----------------
|
|
State Variables
|
|
~~~~~~~~~~~~~~~
|
|
.. bro:id:: Example::example_ports
|
|
|
|
:Type: :bro:type:`set` [:bro:type:`port`]
|
|
:Attributes: :bro:attr:`&redef`
|
|
:Default:
|
|
|
|
::
|
|
|
|
{
|
|
443/tcp,
|
|
562/tcp
|
|
}
|
|
|
|
Types
|
|
~~~~~
|
|
.. bro:type:: Example::PrivateRecord
|
|
|
|
:Type: :bro:type:`record`
|
|
|
|
field1: :bro:type:`bool`
|
|
|
|
field2: :bro:type:`count`
|
|
|
|
Functions
|
|
~~~~~~~~~
|
|
.. bro:id:: Example::filter_func
|
|
|
|
:Type: :bro:type:`function` (rec: :bro:type:`Example::Info`) : :bro:type:`bool`
|
|
|
|
.. bro:id:: Example::function_without_proto
|
|
|
|
:Type: :bro:type:`function` (tag: :bro:type:`string`) : :bro:type:`string`
|
|
|