Merge remote branch 'origin/topic/jsiwek/doc-framework'

testing/btest/Baseline/doc.autogen-reST-enums/autogen-reST-enums.rst

@@ -0,0 +1,99 @@
+.. Automatically generated.  Do not edit.
+
+autogen-reST-enums.bro
+======================
+
+:download:`Original Source File <autogen-reST-enums.bro>`
+
+Overview
+--------
+
+
+Summary
+~~~~~~~
+Types
+#####
+======================================= ======================================
+:bro:type:`TestEnum1`: :bro:type:`enum` There's tons of ways an enum can look.
+
+:bro:type:`TestEnum2`: :bro:type:`enum` The final comma is optional
+======================================= ======================================
+
+Redefinitions
+#############
+======================================= =======================
+:bro:type:`TestEnum1`: :bro:type:`enum` redefs should also work
+
+:bro:type:`TestEnum1`: :bro:type:`enum` now with a comma
+======================================= =======================
+
+Public Interface
+----------------
+Types
+~~~~~
+.. bro:type:: TestEnum1
+
+   :Type: :bro:type:`enum`
+
+      .. bro:enum:: ONE TestEnum1
+
+         like this
+
+      .. bro:enum:: TWO TestEnum1
+
+         or like this
+
+      .. bro:enum:: THREE TestEnum1
+
+         multiple
+         comments
+         and even
+         more comments
+
+   There's tons of ways an enum can look...
+
+.. bro:type:: TestEnum2
+
+   :Type: :bro:type:`enum`
+
+      .. bro:enum:: A TestEnum2
+
+         like this
+
+      .. bro:enum:: B TestEnum2
+
+         or like this
+
+      .. bro:enum:: C TestEnum2
+
+         multiple
+         comments
+         and even
+         more comments
+
+   The final comma is optional
+
+Redefinitions
+~~~~~~~~~~~~~
+:bro:type:`TestEnum1`
+
+   :Type: :bro:type:`enum`
+
+      .. bro:enum:: FOUR TestEnum1
+
+         adding another
+         value
+
+   redefs should also work
+
+:bro:type:`TestEnum1`
+
+   :Type: :bro:type:`enum`
+
+      .. bro:enum:: FIVE TestEnum1
+
+         adding another
+         value
+
+   now with a comma
+

testing/btest/Baseline/doc.autogen-reST-example/example.rst

@@ -0,0 +1,282 @@
+.. 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
+
+:Author: Jon Siwek <jsiwek@ncsa.illinois.edu>
+
+:Imports: :doc:`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
+====================================================== ==========================================================
+
+Events
+######
+============================================== ==========================
+:bro:id:`Example::an_event`: :bro:type:`event` Summarize "an_event" here.
+============================================== ==========================
+
+Functions
+#########
+=============================================== =======================================
+:bro:id:`Example::a_function`: :bro:type:`func` Summarize purpose of "a_function" here.
+=============================================== =======================================
+
+Redefinitions
+#############
+================================================= ====================================
+:bro:type:`Example::SimpleEnum`: :bro:type:`enum` document the "SimpleEnum" 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
+
+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
+
+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:`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
+
+Port Analysis
+-------------
+:ref:`More Information <common_port_analysis_doc>`
+
+SSL::
+
+    [ports={
+        563/tcp,
+        443/tcp
+    }]
+
+Packet Filter
+-------------
+:ref:`More Information <common_packet_filter_doc>`
+
+Filters added::
+
+    [nntps] = tcp port 563,
+    [ssl] = tcp port 443
+
+Private Interface
+-----------------
+State Variables
+~~~~~~~~~~~~~~~
+.. bro:id:: Example::example_ports
+
+   :Type: :bro:type:`set` [:bro:type:`port`]
+   :Attributes: :bro:attr:`&redef`
+   :Default:
+
+   ::
+
+      {
+         563/tcp,
+         443/tcp
+      }
+
+Types
+~~~~~
+.. bro:type:: Example::PrivateRecord
+
+   :Type: :bro:type:`record`
+
+      field1: :bro:type:`bool`
+
+      field2: :bro:type:`count`
+
+Functions
+~~~~~~~~~
+.. bro:id:: Example::function_without_proto
+
+   :Type: :bro:type:`function` (tag: :bro:type:`string`) : :bro:type:`string`
+

testing/btest/Baseline/doc.autogen-reST-records/autogen-reST-records.rst

@@ -0,0 +1,52 @@
+.. Automatically generated.  Do not edit.
+
+autogen-reST-records.bro
+========================
+
+:download:`Original Source File <autogen-reST-records.bro>`
+
+Overview
+--------
+
+
+Summary
+~~~~~~~
+Types
+#####
+============================================ ============================================================
+:bro:type:`SimpleRecord`: :bro:type:`record`
+
+:bro:type:`TestRecord`: :bro:type:`record`   Here's the ways records and record fields can be documented.
+============================================ ============================================================
+
+Public Interface
+----------------
+Types
+~~~~~
+.. bro:type:: SimpleRecord
+
+   :Type: :bro:type:`record`
+
+      field1: :bro:type:`bool`
+
+      field2: :bro:type:`count`
+
+.. bro:type:: TestRecord
+
+   :Type: :bro:type:`record`
+
+      A: :bro:type:`count`
+         document ``A``
+
+      B: :bro:type:`bool`
+         document ``B``
+
+      C: :bro:type:`SimpleRecord`
+         and now ``C``
+         is a declared type
+
+      D: :bro:type:`set` [:bro:type:`count`, :bro:type:`bool`]
+         sets/tables should show the index types
+
+   Here's the ways records and record fields can be documented.
+

testing/btest/Baseline/doc.autogen-reST-type-aliases/autogen-reST-type-aliases.rst

@@ -0,0 +1,61 @@
+.. Automatically generated.  Do not edit.
+
+autogen-reST-type-aliases.bro
+=============================
+
+:download:`Original Source File <autogen-reST-type-aliases.bro>`
+
+Overview
+--------
+
+
+Summary
+~~~~~~~
+State Variables
+###############
+======================================= =======================================================
+:bro:id:`a`: :bro:type:`TypeAlias`      But this should reference a type of ``TypeAlias``.
+
+:bro:id:`b`: :bro:type:`OtherTypeAlias` And this should reference a type of ``OtherTypeAlias``.
+======================================= =======================================================
+
+Types
+#####
+============================================ ==========================================================================
+:bro:type:`TypeAlias`: :bro:type:`bool`      This is just an alias for a builtin type ``bool``.
+
+:bro:type:`OtherTypeAlias`: :bro:type:`bool` We decided that creating alias "chains" might now be so useful to document
+                                             so this type just creates a cross reference to ``bool``.
+============================================ ==========================================================================
+
+Public Interface
+----------------
+State Variables
+~~~~~~~~~~~~~~~
+.. bro:id:: a
+
+   :Type: :bro:type:`TypeAlias`
+
+   But this should reference a type of ``TypeAlias``.
+
+.. bro:id:: b
+
+   :Type: :bro:type:`OtherTypeAlias`
+
+   And this should reference a type of ``OtherTypeAlias``.
+
+Types
+~~~~~
+.. bro:type:: TypeAlias
+
+   :Type: :bro:type:`bool`
+
+   This is just an alias for a builtin type ``bool``.
+
+.. bro:type:: OtherTypeAlias
+
+   :Type: :bro:type:`bool`
+
+   We decided that creating alias "chains" might now be so useful to document
+   so this type just creates a cross reference to ``bool``.
+

testing/btest/btest.cfg

@@ -1,6 +1,6 @@
 
 [btest]
-TestDirs    =
+TestDirs    = doc
 TmpDir      = %(testbase)s/.tmp
 BaselineDir = %(testbase)s/Baseline
 IgnoreDirs  = .svn CVS .tmp

testing/btest/doc/autogen-reST-enums.bro

@@ -0,0 +1,36 @@
+# @TEST-EXEC: bro --doc-scripts %INPUT
+# @TEST-EXEC: btest-diff autogen-reST-enums.rst
+
+## There's tons of ways an enum can look...
+type TestEnum1: enum {
+    ## like this
+    ONE,
+    TWO, ##< or like this
+    ## multiple
+    ## comments
+    THREE, ##< and even
+           ##< more comments
+};
+
+## The final comma is optional
+type TestEnum2: enum {
+    ## like this
+    A,
+    B, ##< or like this
+    ## multiple
+    ## comments
+    C  ##< and even
+           ##< more comments
+};
+
+## redefs should also work
+redef enum TestEnum1 += {
+    ## adding another
+    FOUR ##< value
+};
+
+## now with a comma
+redef enum TestEnum1 += {
+    ## adding another
+    FIVE, ##< value
+};

testing/btest/doc/autogen-reST-example

@@ -0,0 +1,2 @@
+@TEST-EXEC: bro --doc-scripts $DIST/doc/example.bro
+@TEST-EXEC: btest-diff example.rst

testing/btest/doc/autogen-reST-records.bro

@@ -0,0 +1,22 @@
+# @TEST-EXEC: bro --doc-scripts %INPUT
+# @TEST-EXEC: btest-diff autogen-reST-records.rst
+
+# undocumented record
+type SimpleRecord: record {
+    field1: bool;
+    field2: count;
+};
+
+## Here's the ways records and record fields can be documented.
+type TestRecord: record {
+    ## document ``A``
+    A: count;
+
+    B: bool;  ##< document ``B``
+
+    ## and now ``C``
+    C: SimpleRecord; ##< is a declared type
+
+    ## sets/tables should show the index types
+    D: set[count, bool];
+};

testing/btest/doc/autogen-reST-type-aliases.bro

@@ -0,0 +1,15 @@
+# @TEST-EXEC: bro --doc-scripts %INPUT
+# @TEST-EXEC: btest-diff autogen-reST-type-aliases.rst
+
+## This is just an alias for a builtin type ``bool``.
+type TypeAlias: bool;
+
+## We decided that creating alias "chains" might now be so useful to document
+## so this type just creates a cross reference to ``bool``.
+type OtherTypeAlias: TypeAlias;
+
+## But this should reference a type of ``TypeAlias``.
+global a: TypeAlias;
+
+## And this should reference a type of ``OtherTypeAlias``.
+global b: OtherTypeAlias;