diff --git a/doc/scripts/example.bro b/doc/scripts/example.bro index 0b283d028a..c239f2d2a2 100644 --- a/doc/scripts/example.bro +++ b/doc/scripts/example.bro @@ -5,20 +5,6 @@ ##! (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 # Comments that use a single pound sign (#) are not significant to # a script's auto-generated documentation, but ones that use a diff --git a/src/BroDoc.cc b/src/BroDoc.cc index d3406ad113..2ffda01680 100644 --- a/src/BroDoc.cc +++ b/src/BroDoc.cc @@ -227,6 +227,7 @@ void BroDoc::WriteDocFile() const WriteToDoc("%s\n", packet_filter.c_str()); } +/* BroDocObjList::const_iterator it; bool hasPrivateIdentifiers = false; @@ -241,6 +242,7 @@ void BroDoc::WriteDocFile() const if ( hasPrivateIdentifiers ) WriteInterface("Private Interface", '-', '~', false, false); +*/ } void BroDoc::WriteInterface(const char* heading, char underline, diff --git a/src/BroDoc.h b/src/BroDoc.h index 112401253c..ac6ff0a59b 100644 --- a/src/BroDoc.h +++ b/src/BroDoc.h @@ -167,6 +167,18 @@ public: all.push_back(o); } + /** + * Schedules documentation of an event handler declared by the script. + * @param o A pointer to a BroDocObj which contains the internal + * Bro language representation of the script event handler and + * also any associated comments about it. + */ + void AddEventHandler(const BroDocObj* o) + { + event_handlers.push_back(o); + all.push_back(o); + } + /** * Schedules documentation of a function declared by the script. * @param o A pointer to a BroDocObj which contains the internal @@ -228,6 +240,7 @@ protected: BroDocObjList types; BroDocObjList notices; BroDocObjList events; + BroDocObjList event_handlers; BroDocObjMap functions; BroDocObjList redefs; diff --git a/src/parse.y b/src/parse.y index 2eb84680b7..2410358f81 100644 --- a/src/parse.y +++ b/src/parse.y @@ -1179,7 +1179,7 @@ func_hdr: FUNC_FLAVOR_EVENT, 0, $3); $$ = $3; if ( generate_documentation ) - current_reST_doc->AddEvent( + current_reST_doc->AddEventHandler( new BroDocObj($2, reST_doc_comments)); } | TOK_REDEF TOK_EVENT event_id func_params diff --git a/testing/btest/Baseline/doc.autogen-reST-example/example.rst b/testing/btest/Baseline/doc.autogen-reST-example/example.rst index f6f7b4b2fc..b76b9af59b 100644 --- a/testing/btest/Baseline/doc.autogen-reST-example/example.rst +++ b/testing/btest/Baseline/doc.autogen-reST-example/example.rst @@ -15,20 +15,6 @@ these comments are transferred directly into the auto-generated .. 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 - :Imports: :doc:`policy/frameworks/software/vulnerable ` Summary @@ -72,8 +58,6 @@ Events :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 @@ -233,10 +217,6 @@ Events 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 @@ -309,40 +289,3 @@ 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` -