mirror of
https://github.com/zeek/zeek.git
synced 2025-10-07 17:18:20 +00:00
5a2cd265ab
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.
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 </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`
|
|
|