.. 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:`notice </policy/notice>`

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: :bro:type:`enum`

      .. bro:enum:: Example::Notice_One Notice

         any number of this type of comment
         will document "Notice_One"

      .. bro:enum:: Example::Notice_Two Notice

         any number of this type of comment
         will document "Notice_Two"

      .. bro:enum:: Example::Notice_Three Notice

      .. bro:enum:: Example::Notice_Four Notice

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`

