Broxygen doc-related test updates. Fix two regressions.

- Fix automatic function parameter documentation formatting for
  record fields that are functions.

- Document redefs in a fixed order.

scripts/broxygen/example.bro

@@ -1,20 +1,24 @@
-##! This is an example script that demonstrates documentation features.
+##! This is an example script that demonstrates Broxygen-style
-##! Comments of the form ``##!`` are for the script summary.  The contents of
+##! documentation.  It generally will make most sense when viewing
-##! these comments are transferred directly into the auto-generated
+##! the script's raw source code and comparing to the HTML-rendered
+##! version.
+##!
+##! Comments in the from ``##!`` are meant to summarize the script's
+##! purpose.  They are transferred directly in to the generated
 ##! `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
-##! (reST) document's summary section.
+##! (reST) document associated with the script.
 ##!
 ##! .. tip:: You can embed directives and roles within ``##``-stylized comments.
 ##!
 ##! There's also a custom role to reference any identifier node in
 ##! the Bro Sphinx domain that's good for "see alsos", e.g.
 ##!
-##! See also: :bro:see:`Example::a_var`, :bro:see:`Example::ONE`,
+##! See also: :bro:see:`BroxygenExample::a_var`,
-##! :bro:see:`SSH::Info`
+##! :bro:see:`BroxygenExample::ONE`, :bro:see:`SSH::Info`
 ##!
 ##! And a custom directive does the equivalent references:
 ##!
-##! .. bro:see:: Example::a_var Example::ONE SSH::Info
+##! .. bro:see:: BroxygenExample::a_var BroxygenExample::ONE SSH::Info
 
 # Comments that use a single pound sign (#) are not significant to
 # a script's auto-generated documentation, but ones that use a
@@ -26,7 +30,7 @@
 # variable declarations to associate with the last-declared identifier.
 #
 # Generally, the auto-doc comments (##) are associated with the
-# next declaration/identifier found in the script, but the doc framework
+# next declaration/identifier found in the script, but Broxygen
 # will track/render identifiers regardless of whether they have any
 # of these special comments associated with them.
 #
@@ -37,193 +41,154 @@
 # in the "##"-stylized comments up until the first empty comment
 # is taken as the summary text for a given identifier.
 
-# @load directives are self-documenting
+# @load directives are self-documenting, don't use any ``##`` style
+# comments with them.
+@load base/frameworks/notice
+@load base/protocols/http
 @load frameworks/software/vulnerable
 
-# "module" statements are self-documenting
+# "module" statements are self-documenting, don't use any ``##`` style
-module Example;
+# comments with them.
+module BroxygenExample;
 
-# redefinitions of "capture_filters" are self-documenting and
+# Redefinitions of "Notice::Type" are self-documenting, but
-# go into the generated documentation's "Packet Filter" section
+# more information can be supplied in two different ways.
-redef capture_filters += {
-    ["ssl"] = "tcp port 443",
-    ["nntps"] = "tcp port 562",
-};
-
-global example_ports = {
-    443/tcp, 562/tcp,
-} &redef;
-
-
-event bro_init()
-	{
-	Analyzer::register_for_ports(Analyzer::ANALYZER_SSL, example_ports);
-	}
-
-# redefinitions of "Notice::Type" are self-documenting, but
-# more information can be supplied in two different ways
 redef enum Notice::Type += {
-    ## any number of this type of comment
+	## Any number of this type of comment
-    ## will document "Notice_One"
+	## will document "Broxygen_One".
-    Notice_One,
+	Broxygen_One,
-    Notice_Two,  ##< any number of this type of comment
+	Broxygen_Two,  ##< Any number of this type of comment
-                 ##< will document "Notice_Two"
+	               ##< will document "BROXYGEN_TWO".
-    Notice_Three,
+	Broxygen_Three,
-    Notice_Four,
+	## Omitting comments is fine, and so is mixing ``##`` and ``##<``, but
+	Broxygen_Four,  ##< it's probably best to use only one style consistently.
 };
 
-# Redef'ing the ID enumeration for logging streams is automatically tracked.
+# All redefs are automatically tracked.  Comments of the "##" form can be use
-# Comments of the "##" form can be use to further document it, but it's
+# to further document it, but in some cases, like here, they wouldn't be
-# better to do all documentation related to logging in the summary section
+# ading any interesting information that's not implicit.
-# as is shown above.
 redef enum Log::ID += { LOG };
 
-# Anything declared in the export section will show up in the rendered
+# Only identifiers declared in an export section will show up in generated docs.
-# documentation's "public interface" section
 
 export {
 
-    # these headings don't mean anything special to the
+	## Documentation for the "SimpleEnum" type goes here.
-    # doc framework right now, I'm just including them
+	## It can span multiple lines.
-    # to make it more clear to the reader how the doc
+	type SimpleEnum: enum {
-    # framework will actually categorize a script's identifiers
+		## Documentation for particular enum values is added like this.
+		## And can also span multiple lines.
+		ONE,
+		TWO,  ##< Or this style is valid to document the preceding enum value.
+		THREE,
+	};
 
-    ############## types ################
+	## Document the "SimpleEnum" redef here with any special info regarding
+	## the *redef* itself.
+	redef enum SimpleEnum  += {
+		FOUR, ##< And some documentation for "FOUR".
+		## Also "FIVE".
+		FIVE
+	};
 
-    # Note that I'm just mixing the "##" and "##<"
+	## General documentation for a type "SimpleRecord" goes here.
-    # types of comments in the following declarations
+	## The way fields can be documented is similar to what's already seen
-    # as a demonstration.  Normally, it would be good style
+	## for enums.
-    # to pick one and be consistent.
+	type SimpleRecord: record {
+		## Counts something.
+		field1: count;
+		field2: bool; ##< Toggles something.
+	};
 
-    ## documentation for "SimpleEnum"
+	## Document the record extension *redef* itself here.
-    ## goes here.
+	redef record SimpleRecord += {
-    type SimpleEnum: enum {
+		## Document the extending field like this.
-        ## and more specific info for "ONE"
+		field_ext: string &optional; ##< Or here, like this.
-        ## can span multiple lines
+	};
-        ONE,
-        TWO,  ##< or more info like this for "TWO"
-              ##< can span multiple lines
-        THREE,
-    };
 
-    ## document the "SimpleEnum" redef here
+	## General documentation for a type "ComplexRecord" goes here.
-    redef enum SimpleEnum  += {
+	type ComplexRecord: record {
-        FOUR, ##< and some documentation for "FOUR"
+		field1: count;               ##< Counts something.
-        ## also "FIVE" for good measure
+		field2: bool;                ##< Toggles something.
-        FIVE
+		field3: SimpleRecord;        ##< Broxygen automatically tracks types
-    };
+		                             ##< and cross-references are automatically
+		                             ##< inserted in to generated docs.
+		msg: string &default="blah"; ##< Attributes are self-documenting.
+	} &redef;
 
-    ## general documentation for a type "SimpleRecord"
+	## An example record to be used with a logging stream.
-    ## goes here.
+	## Nothing special about it.  If another script redefs this type
-    type SimpleRecord: record {
+	## to add fields, the generated documentation will show all original
-        ## counts something
+	## fields plus the extensions and the scripts which contributed to it
-        field1: count;
+	## (provided they are also @load'ed).
-        field2: bool; ##< toggles something
+	type Info: record {
-    };
+		ts:       time       &log;
+		uid:      string     &log;
+		status:   count      &log &optional;
+	};
 
-    ## document the record extension redef here
+	## Add documentation for "an_option" here.
-    redef record SimpleRecord += {
+	## The type/attribute information is all generated automatically.
-        ## document the extending field here
+	const an_option: set[addr, addr, string] &redef;
-        field_ext: string &optional; ##< (or here)
-    };
 
-    ## general documentation for a type "ComplexRecord" goes here
+	## Default initialization will be generated automatically.
-    type ComplexRecord: record {
+	const option_with_init = 0.01 secs &redef; ##< More docs can be added here.
-        field1: count;               ##< counts something
-        field2: bool;                ##< toggles something
-        field3: SimpleRecord;
-        msg: string &default="blah"; ##< attributes are self-documenting
-    } &redef;
 
-    ## An example record to be used with a logging stream.
+	## Put some documentation for "a_var" here.  Any global/non-const that
-    type Info: record {
+	## isn't a function/event/hook is classified as a "state variable"
-        ts:       time       &log;
+	## in the generated docs.
-        uid:      string     &log;
+	global a_var: bool;
-        status:   count      &log &optional;
-    };
 
-    ############## options ################
+	## Types are inferred, that information is self-documenting.
-    # right now, I'm just defining an option as
+	global var_without_explicit_type = "this works";
-    # any const with &redef (something that can
-    # change at parse time, but not at run time.
 
-    ## add documentation for "an_option" here
+	## The first sentence for a particular identifier's summary text ends here.
-    const an_option: set[addr, addr, string] &redef;
+	## And this second sentence doesn't show in the short description provided
-
+	## by the table of all identifiers declared by this script.
-    # default initialization will be self-documenting
+	global summary_test: string;
-    const option_with_init = 0.01 secs &redef; ##< More docs can be added here.
-
-    ############## state variables ############
-    # right now, I'm defining this as any global
-    # that's not a function/event.  doesn't matter
-    # if &redef attribute is present
-
-    ## put some documentation for "a_var" here
-    global a_var: bool;
-
-    # attributes are self-documenting
-    global var_with_attr: count &persistent;
-
-    # it's fine if the type is inferred, that information is self-documenting
-    global var_without_explicit_type = "this works";
-
-    ## The first.sentence for the summary text ends here.  And this second
-    ## sentence doesn't show in the short description.
-    global dummy: string;
-
-    ############## functions/events ############
 
     ## 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.
     ##
-    ## tag: function arguments can be described
+    ## tag: Function arguments can be described
-    ##      like this
+    ##      like this.
-    ## msg: another param
+	##
+    ## msg: Another param.
     ##
-    ## Returns: describe the return type here
+    ## Returns: Describe the return type here.
     global a_function: function(tag: string, msg: string): string;
 
     ## Summarize "an_event" here.
     ## Give more details about "an_event" here.
-	## Example::an_event should not be confused as a parameter.
+	##
-    ## name: describe the argument here
+	## BroxygenExample::a_function should not be confused as a parameter
+	## in the generated docs, but it also doesn't generate a cross-reference
+	## link.  Use the see role instead: :bro:see:`BroxygenExample::a_function`.
+	##
+    ## name: Describe the argument here.
     global an_event: event(name: string);
-
-    ## This is a declaration of an example event that can be used in
-    ## logging streams and is raised once for each log entry.
-    global log_example: event(rec: Info);
 }
 
-function filter_func(rec: Info): bool
+# This function isn't exported, so it won't appear anywhere in the generated
-    {
+# documentation.  So using ``##``-style comments is pointless here.
-    return T;
-    }
-
-# this function is documented in the "private interface" section
-# of generated documentation and any "##"-stylized comments would also
-# be rendered there
 function function_without_proto(tag: string): string
     {
     return "blah";
     }
 
-# this record type is documented in the "private interface" section
+# Same thing goes for types -- it's not exported, so it's considered
-# of generated documentation and any "##"-stylized comments would also
+# private to this script and comments are only interesting to a person
-# be rendered there
+# who is already reading the raw source for the script (so don't use
+# ``##`` comments here.
 type PrivateRecord: record {
     field1: bool;
     field2: count;
 };
 
+# Event handlers are also an implementation detail of a script, so they
+# don't show up anywhere in the generated documentation.
 event bro_init()
     {
-    Log::create_stream(Example::LOG, [$columns=Info, $ev=log_example]);
-    Log::add_filter(Example::LOG, [
-        $name="example-filter",
-        $path="example-filter",
-        $pred=filter_func,
-        $exclude=set("ts")
-        ]);
     }

src/Type.cc

@@ -9,6 +9,7 @@
 #include "Serializer.h"
 #include "Reporter.h"
 #include "broxygen/Manager.h"
+#include "broxygen/utils.h"
 
 #include <string>
 #include <list>
@@ -1182,7 +1183,17 @@ void RecordType::DescribeFieldsReST(ODesc* d, bool func_args) const
 			if ( i > 0 )
 				d->NL();
 
-			d->Add(cmnts[i].c_str());
+			if ( IsFunc(td->type->Tag()) )
+				{
+				string s = cmnts[i];
+
+				if ( broxygen::prettify_params(s) )
+					d->NL();
+
+				d->Add(s.c_str());
+				}
+			else
+				d->Add(cmnts[i].c_str());
 			}
 
 		d->PopIndentNoNL();

src/broxygen/CMakeLists.txt

@@ -9,6 +9,7 @@ set(broxygen_SRCS
     Configuration.cc
     Document.cc
     Manager.cc
+    utils.cc
 )
 
 bif_target(broxygen.bif)

src/broxygen/Document.cc

@@ -1,5 +1,6 @@
 #include "Document.h"
 #include "Manager.h"
+#include "utils.h"
 
 #include "util.h"
 #include "Val.h"
@@ -18,72 +19,6 @@ static bool is_public_api(const ID* id)
 	       (id->Scope() == SCOPE_MODULE && id->IsExport());
 	}
 
-static bool prettify_params(string& s)
-	{
-	size_t identifier_start_pos = 0;
-	bool in_identifier = false;
-	string identifier;
-
-	for ( size_t i = 0; i < s.size(); ++i )
-		{
-		char next = s[i];
-
-		if ( ! in_identifier )
-			{
-			// Pass by leading whitespace.
-			if ( isspace(next) )
-				continue;
-
-			// Only allow alphabetic and '_' as first char of identifier.
-			if ( isalpha(next) || next == '_' )
-				{
-				identifier_start_pos = i;
-				identifier += next;
-				in_identifier = true;
-				continue;
-				}
-
-			// Don't need to change anything.
-			return false;
-			}
-
-		// All other characters of identifier are alphanumeric or '_'.
-		if ( isalnum(next) || next == '_' )
-			{
-			identifier += next;
-			continue;
-			}
-
-		if ( next == ':' )
-			{
-			if ( i + 1 < s.size() && s[i + 1] == ':' )
-				{
-				// It's part of an identifier's namespace scoping.
-				identifier += next;
-				identifier += s[i + 1];
-				++i;
-				continue;
-				}
-
-			// Prettify function param/return value reST markup.
-			string subst;
-
-			if ( identifier == "Returns" )
-				subst = ":returns";
-			else
-				subst = ":param " + identifier;
-
-			s.replace(identifier_start_pos, identifier.size(), subst);
-			return true;
-			}
-
-		// Don't need to change anything.
-		return false;
-		}
-
-	return false;
-	}
-
 static string make_heading(const string& heading, char underline)
 	{
 	return heading + "\n" + string(heading.size(), underline) + "\n";
@@ -244,7 +179,7 @@ string IdentifierDocument::DoReStructuredText(bool roles_only) const
 			{
 			string s = comments[i];
 
-			if ( prettify_params(s) )
+			if ( broxygen::prettify_params(s) )
 				d.NL();
 
 			d.Add(s.c_str());
@@ -523,15 +458,15 @@ static string make_summary(const string& heading, char underline, char border,
 
 static string make_redef_summary(const string& heading, char underline,
                                  char border, const string& from_script,
-                                 const set<IdentifierDocument*>& id_set)
+                                 const id_doc_set& id_set)
 	{
 	if ( id_set.empty() )
 		return "";
 
 	ReStructuredTextTable table(2);
 
-	for ( set<IdentifierDocument*>::const_iterator it = id_set.begin();
+	for ( id_doc_set::const_iterator it = id_set.begin(); it != id_set.end();
-	      it != id_set.end(); ++it )
+	      ++it )
 		{
 		ID* id = (*it)->GetID();
 		ODesc d;
@@ -568,14 +503,14 @@ static string make_details(const string& heading, char underline,
 	}
 
 static string make_redef_details(const string& heading, char underline,
-                                 const set<IdentifierDocument*>& id_set)
+                                 const id_doc_set& id_set)
 	{
 	if ( id_set.empty() )
 		return "";
 
 	string rval = make_heading(heading, underline);
 
-	for ( set<IdentifierDocument*>::const_iterator it = id_set.begin();
+	for ( id_doc_set::const_iterator it = id_set.begin();
 	      it != id_set.end(); ++it )
 		{
 		rval += (*it)->ReStructuredText(true);

src/broxygen/Document.h

@@ -145,6 +145,13 @@ private:
 	ScriptDocument* declaring_script;
 };
 
+struct IdDocComp {
+	bool operator() (IdentifierDocument* lhs, IdentifierDocument* rhs) const
+		{ return lhs->Name() < rhs->Name(); }
+};
+
+typedef std::set<IdentifierDocument*, IdDocComp> id_doc_set;
+
 class ScriptDocument : public Document {
 
 public:
@@ -175,7 +182,6 @@ private:
 	typedef std::map<std::string, IdentifierDocument*> id_doc_map;
 	typedef std::list<IdentifierDocument*> id_doc_list;
 	typedef std::set<std::string> string_set;
-	typedef std::set<IdentifierDocument*> doc_set;
 
 	time_t DoGetModificationTime() const;
 
@@ -200,7 +206,7 @@ private:
 	id_doc_list events;
 	id_doc_list hooks;
 	id_doc_list functions;
-	doc_set redefs;
+	id_doc_set redefs;
 };
 
 

src/broxygen/utils.cc

@@ -0,0 +1,70 @@
+#include "utils.h"
+
+using namespace broxygen;
+using namespace std;
+
+bool broxygen::prettify_params(string& s)
+	{
+	size_t identifier_start_pos = 0;
+	bool in_identifier = false;
+	string identifier;
+
+	for ( size_t i = 0; i < s.size(); ++i )
+		{
+		char next = s[i];
+
+		if ( ! in_identifier )
+			{
+			// Pass by leading whitespace.
+			if ( isspace(next) )
+				continue;
+
+			// Only allow alphabetic and '_' as first char of identifier.
+			if ( isalpha(next) || next == '_' )
+				{
+				identifier_start_pos = i;
+				identifier += next;
+				in_identifier = true;
+				continue;
+				}
+
+			// Don't need to change anything.
+			return false;
+			}
+
+		// All other characters of identifier are alphanumeric or '_'.
+		if ( isalnum(next) || next == '_' )
+			{
+			identifier += next;
+			continue;
+			}
+
+		if ( next == ':' )
+			{
+			if ( i + 1 < s.size() && s[i + 1] == ':' )
+				{
+				// It's part of an identifier's namespace scoping.
+				identifier += next;
+				identifier += s[i + 1];
+				++i;
+				continue;
+				}
+
+			// Prettify function param/return value reST markup.
+			string subst;
+
+			if ( identifier == "Returns" )
+				subst = ":returns";
+			else
+				subst = ":param " + identifier;
+
+			s.replace(identifier_start_pos, identifier.size(), subst);
+			return true;
+			}
+
+		// Don't need to change anything.
+		return false;
+		}
+
+	return false;
+	}

src/broxygen/utils.h

@@ -0,0 +1,12 @@
+#ifndef BROXYGEN_UTILS_H
+#define BROXYGEN_UTILS_H
+
+#include <string>
+
+namespace broxygen {
+
+bool prettify_params(std::string& s);
+
+} // namespace broxygen
+
+#endif

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

@@ -1,116 +0,0 @@
-.. Automatically generated.  Do not edit.
-
-:tocdepth: 3
-
-autogen-reST-enums.bro
-======================
-
-
-
-
-:Source File: :download:`autogen-reST-enums.bro`
-
-Summary
-~~~~~~~
-Options
-#######
-==================================================================== ======================================================================
-:bro:id:`test_enum_option`: :bro:type:`TestEnum1` :bro:attr:`&redef` this should reference the TestEnum1 type and not a generic "enum" type
-==================================================================== ======================================================================
-
-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
-======================================= =======================
-
-Detailed Interface
-~~~~~~~~~~~~~~~~~~
-Options
-#######
-.. bro:id:: test_enum_option
-
-   :Type: :bro:type:`TestEnum1`
-   :Attributes: :bro:attr:`&redef`
-   :Default: ``ONE``
-
-   this should reference the TestEnum1 type and not a generic "enum" type
-
-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

@@ -1,301 +0,0 @@
-.. Automatically generated.  Do not edit.
-
-:tocdepth: 3
-
-example.bro
-===========
-.. bro:namespace:: Example
-
-This is an example script that demonstrates documentation features.
-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.
-
-There's also a custom role to reference any identifier node in
-the Bro Sphinx domain that's good for "see alsos", e.g.
-
-See also: :bro:see:`Example::a_var`, :bro:see:`Example::ONE`,
-:bro:see:`SSH::Info`
-
-And a custom directive does the equivalent references:
-
-.. bro:see:: Example::a_var Example::ONE SSH::Info
-
-:Namespace: ``Example``
-:Imports: :doc:`policy/frameworks/software/vulnerable </scripts/policy/frameworks/software/vulnerable>`
-:Source File: :download:`example.bro`
-
-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` More docs can be added here.
-============================================================================ ======================================
-
-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`
-
-:bro:id:`Example::dummy`: :bro:type:`string`                                The first.sentence for the summary text ends here.
-=========================================================================== ==================================================
-
-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.
-================================================= =============================================================
-
-Functions
-#########
-=================================================== =======================================
-:bro:id:`Example::a_function`: :bro:type:`function` 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
-===================================================== ========================================
-
-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
-
-Configuration Changes
-#####################
-Packet Filter
-^^^^^^^^^^^^^
-Loading this script makes the following changes to :bro:see:`capture_filters`.
-
-Filters added::
-
-    [ssl] = tcp port 443,
-    [nntps] = tcp port 562
-
-Detailed 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``
-
-   More docs can be added here.
-
-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"``
-
-.. bro:id:: Example::dummy
-
-   :Type: :bro:type:`string`
-
-   The first.sentence for the summary text ends here.  And this second
-   sentence doesn't show in the short description.
-
-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.
-   Example::an_event should not be confused as a parameter.
-   
-   :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.
-
-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::LOG 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
-

testing/btest/Baseline/doc.autogen-reST-func-params/autogen-reST-func-params.rst

@@ -1,58 +0,0 @@
-.. Automatically generated.  Do not edit.
-
-:tocdepth: 3
-
-autogen-reST-func-params.bro
-============================
-
-
-
-
-:Source File: :download:`autogen-reST-func-params.bro`
-
-Summary
-~~~~~~~
-Types
-#####
-======================================== =
-:bro:type:`test_rec`: :bro:type:`record`
-======================================== =
-
-Functions
-#########
-========================================= ======================================
-:bro:id:`test_func`: :bro:type:`function` This is a global function declaration.
-========================================= ======================================
-
-Detailed Interface
-~~~~~~~~~~~~~~~~~~
-Types
-#####
-.. bro:type:: test_rec
-
-   :Type: :bro:type:`record`
-
-      field_func: :bro:type:`function` (i: :bro:type:`int`, j: :bro:type:`int`) : :bro:type:`string`
-         This is a record field function.
-         
-         :param i: First param.
-         :param j: Second param.
-         
-         :returns: A string.
-
-Functions
-#########
-.. bro:id:: test_func
-
-   :Type: :bro:type:`function` (i: :bro:type:`int`, j: :bro:type:`int`) : :bro:type:`string`
-
-   This is a global function declaration.
-   
-   
-   :param i: First param.
-   
-   :param j: Second param.
-   
-   
-   :returns: A string.
-

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

@@ -1,53 +0,0 @@
-.. Automatically generated.  Do not edit.
-
-:tocdepth: 3
-
-autogen-reST-records.bro
-========================
-
-
-
-
-:Source File: :download:`autogen-reST-records.bro`
-
-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.
-============================================ ============================================================
-
-Detailed 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

@@ -1,62 +0,0 @@
-.. Automatically generated.  Do not edit.
-
-:tocdepth: 3
-
-autogen-reST-type-aliases.bro
-=============================
-
-
-
-
-:Source File: :download:`autogen-reST-type-aliases.bro`
-
-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 not be so useful to document
-                                             so this type just creates a cross reference to ``bool``.
-============================================ ==========================================================================
-
-Detailed 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 not be so useful to document
-   so this type just creates a cross reference to ``bool``.
-

testing/btest/Baseline/doc.broxygen.all_scripts/.stdout

@@ -0,0 +1 @@
+WARNING: No Site::local_nets have been defined.  It's usually a good idea to define your local networks.

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

@@ -0,0 +1,60 @@
+.. 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
+
+      .. bro:enum:: FOUR TestEnum1
+
+         adding another
+         value
+
+      .. bro:enum:: FIVE TestEnum1
+
+         adding another
+         value
+
+   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
+
+.. bro:id:: TestEnumVal
+
+   :Type: :bro:type:`TestEnum1`
+   :Attributes: :bro:attr:`&redef`
+   :Default: ``ONE``
+
+   this should reference the TestEnum1 type and not a generic "enum" type
+

testing/btest/Baseline/doc.broxygen.example/example.rst

@@ -0,0 +1,249 @@
+:tocdepth: 3
+
+broxygen/example.bro
+====================
+.. bro:namespace:: BroxygenExample
+
+This is an example script that demonstrates Broxygen-style
+documentation.  It generally will make most sense when viewing
+the script's raw source code and comparing to the HTML-rendered
+version.
+
+Comments in the from ``##!`` are meant to summarize the script's
+purpose.  They are transferred directly in to the generated
+`reStructuredText <http://docutils.sourceforge.net/rst.html>`_
+(reST) document associated with the script.
+
+.. tip:: You can embed directives and roles within ``##``-stylized comments.
+
+There's also a custom role to reference any identifier node in
+the Bro Sphinx domain that's good for "see alsos", e.g.
+
+See also: :bro:see:`BroxygenExample::a_var`,
+:bro:see:`BroxygenExample::ONE`, :bro:see:`SSH::Info`
+
+And a custom directive does the equivalent references:
+
+.. bro:see:: BroxygenExample::a_var BroxygenExample::ONE SSH::Info
+
+:Namespace: BroxygenExample
+:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/http </scripts/base/protocols/http/index>`, :doc:`policy/frameworks/software/vulnerable.bro </scripts/policy/frameworks/software/vulnerable.bro>`
+:Source File: :download:`/scripts/broxygen/example.bro`
+
+Summary
+~~~~~~~
+Options
+#######
+==================================================================================== =======================================================
+:bro:id:`BroxygenExample::an_option`: :bro:type:`set` :bro:attr:`&redef`             Add documentation for "an_option" here.
+:bro:id:`BroxygenExample::option_with_init`: :bro:type:`interval` :bro:attr:`&redef` Default initialization will be generated automatically.
+==================================================================================== =======================================================
+
+State Variables
+###############
+======================================================================== ========================================================================
+:bro:id:`BroxygenExample::a_var`: :bro:type:`bool`                       Put some documentation for "a_var" here.
+:bro:id:`BroxygenExample::summary_test`: :bro:type:`string`              The first sentence for a particular identifier's summary text ends here.
+:bro:id:`BroxygenExample::var_without_explicit_type`: :bro:type:`string` Types are inferred, that information is self-documenting.
+======================================================================== ========================================================================
+
+Types
+#####
+================================================================================= ===========================================================
+:bro:type:`BroxygenExample::ComplexRecord`: :bro:type:`record` :bro:attr:`&redef` General documentation for a type "ComplexRecord" goes here.
+:bro:type:`BroxygenExample::Info`: :bro:type:`record`                             An example record to be used with a logging stream.
+:bro:type:`BroxygenExample::SimpleEnum`: :bro:type:`enum`                         Documentation for the "SimpleEnum" type goes here.
+:bro:type:`BroxygenExample::SimpleRecord`: :bro:type:`record`                     General documentation for a type "SimpleRecord" goes here.
+================================================================================= ===========================================================
+
+Redefinitions
+#############
+============================================================= ====================================================================
+:bro:type:`BroxygenExample::SimpleEnum`: :bro:type:`enum`     Document the "SimpleEnum" redef here with any special info regarding
+                                                              the *redef* itself.
+:bro:type:`BroxygenExample::SimpleRecord`: :bro:type:`record` Document the record extension *redef* itself here.
+:bro:type:`Log::ID`: :bro:type:`enum`                         
+:bro:type:`Notice::Type`: :bro:type:`enum`                    
+============================================================= ====================================================================
+
+Events
+######
+====================================================== ==========================
+:bro:id:`BroxygenExample::an_event`: :bro:type:`event` Summarize "an_event" here.
+====================================================== ==========================
+
+Functions
+#########
+=========================================================== =======================================
+:bro:id:`BroxygenExample::a_function`: :bro:type:`function` Summarize purpose of "a_function" here.
+=========================================================== =======================================
+
+
+Detailed Interface
+~~~~~~~~~~~~~~~~~~
+Options
+#######
+.. bro:id:: BroxygenExample::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.
+   The type/attribute information is all generated automatically.
+
+.. bro:id:: BroxygenExample::option_with_init
+
+   :Type: :bro:type:`interval`
+   :Attributes: :bro:attr:`&redef`
+   :Default: ``10.0 msecs``
+
+   Default initialization will be generated automatically.
+   More docs can be added here.
+
+State Variables
+###############
+.. bro:id:: BroxygenExample::a_var
+
+   :Type: :bro:type:`bool`
+
+   Put some documentation for "a_var" here.  Any global/non-const that
+   isn't a function/event/hook is classified as a "state variable"
+   in the generated docs.
+
+.. bro:id:: BroxygenExample::summary_test
+
+   :Type: :bro:type:`string`
+
+   The first sentence for a particular identifier's summary text ends here.
+   And this second sentence doesn't show in the short description provided
+   by the table of all identifiers declared by this script.
+
+.. bro:id:: BroxygenExample::var_without_explicit_type
+
+   :Type: :bro:type:`string`
+   :Default: ``"this works"``
+
+   Types are inferred, that information is self-documenting.
+
+Types
+#####
+.. bro:type:: BroxygenExample::ComplexRecord
+
+   :Type: :bro:type:`record`
+
+      field1: :bro:type:`count`
+         Counts something.
+
+      field2: :bro:type:`bool`
+         Toggles something.
+
+      field3: :bro:type:`BroxygenExample::SimpleRecord`
+         Broxygen automatically tracks types
+         and cross-references are automatically
+         inserted in to generated docs.
+
+      msg: :bro:type:`string` :bro:attr:`&default` = ``"blah"`` :bro:attr:`&optional`
+         Attributes are self-documenting.
+   :Attributes: :bro:attr:`&redef`
+
+   General documentation for a type "ComplexRecord" goes here.
+
+.. bro:type:: BroxygenExample::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.
+   Nothing special about it.  If another script redefs this type
+   to add fields, the generated documentation will show all original
+   fields plus the extensions and the scripts which contributed to it
+   (provided they are also @load'ed).
+
+.. bro:type:: BroxygenExample::SimpleEnum
+
+   :Type: :bro:type:`enum`
+
+      .. bro:enum:: BroxygenExample::ONE BroxygenExample::SimpleEnum
+
+         Documentation for particular enum values is added like this.
+         And can also span multiple lines.
+
+      .. bro:enum:: BroxygenExample::TWO BroxygenExample::SimpleEnum
+
+         Or this style is valid to document the preceding enum value.
+
+      .. bro:enum:: BroxygenExample::THREE BroxygenExample::SimpleEnum
+
+      .. bro:enum:: BroxygenExample::FOUR BroxygenExample::SimpleEnum
+
+         And some documentation for "FOUR".
+
+      .. bro:enum:: BroxygenExample::FIVE BroxygenExample::SimpleEnum
+
+         Also "FIVE".
+
+   Documentation for the "SimpleEnum" type goes here.
+   It can span multiple lines.
+
+.. bro:type:: BroxygenExample::SimpleRecord
+
+   :Type: :bro:type:`record`
+
+      field1: :bro:type:`count`
+         Counts something.
+
+      field2: :bro:type:`bool`
+         Toggles something.
+
+      field_ext: :bro:type:`string` :bro:attr:`&optional`
+         Document the extending field like this.
+         Or here, like this.
+
+   General documentation for a type "SimpleRecord" goes here.
+   The way fields can be documented is similar to what's already seen
+   for enums.
+
+Events
+######
+.. bro:id:: BroxygenExample::an_event
+
+   :Type: :bro:type:`event` (name: :bro:type:`string`)
+
+   Summarize "an_event" here.
+   Give more details about "an_event" here.
+   
+   BroxygenExample::a_function should not be confused as a parameter
+   in the generated docs, but it also doesn't generate a cross-reference
+   link.  Use the see role instead: :bro:see:`BroxygenExample::a_function`.
+   
+
+   :param name: Describe the argument here.
+
+Functions
+#########
+.. bro:id:: BroxygenExample::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.
+
+

testing/btest/Baseline/doc.broxygen.func-params/autogen-reST-func-params.rst

@@ -0,0 +1,30 @@
+.. bro:id:: test_func_params_func
+
+   :Type: :bro:type:`function` (i: :bro:type:`int`, j: :bro:type:`int`) : :bro:type:`string`
+
+   This is a global function declaration.
+   
+
+   :param i: First param.
+
+   :param j: Second param.
+   
+
+   :returns: A string.
+
+.. bro:type:: test_func_params_rec
+
+   :Type: :bro:type:`record`
+
+      field_func: :bro:type:`function` (i: :bro:type:`int`, j: :bro:type:`int`) : :bro:type:`string`
+         This is a record field function.
+         
+
+         :param i: First param.
+
+         :param j: Second param.
+         
+
+         :returns: A string.
+
+

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

@@ -0,0 +1,28 @@
+.. bro:type:: TestRecord1
+
+   :Type: :bro:type:`record`
+
+      field1: :bro:type:`bool`
+
+      field2: :bro:type:`count`
+
+
+.. bro:type:: TestRecord2
+
+   :Type: :bro:type:`record`
+
+      A: :bro:type:`count`
+         document ``A``
+
+      B: :bro:type:`bool`
+         document ``B``
+
+      C: :bro:type:`TestRecord1`
+         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.broxygen.type-aliases/autogen-reST-type-aliases.rst

@@ -0,0 +1,44 @@
+.. bro:type:: BroxygenTest::TypeAlias
+
+   :Type: :bro:type:`bool`
+
+   This is just an alias for a builtin type ``bool``.
+
+.. bro:type:: BroxygenTest::NotTypeAlias
+
+   :Type: :bro:type:`bool`
+
+   This type should get its own comments, not associated w/ TypeAlias.
+
+.. bro:type:: BroxygenTest::OtherTypeAlias
+
+   :Type: :bro:type:`bool`
+
+   This cross references ``bool`` in the description of its type
+   instead of ``TypeAlias`` just because it seems more useful --
+   one doesn't have to click through the full type alias chain to
+   find out what the actual type is...
+
+.. bro:id:: BroxygenTest::a
+
+   :Type: :bro:type:`BroxygenTest::TypeAlias`
+
+   But this should reference a type of ``TypeAlias``.
+
+.. bro:id:: BroxygenTest::b
+
+   :Type: :bro:type:`BroxygenTest::OtherTypeAlias`
+
+   And this should reference a type of ``OtherTypeAlias``.
+
+.. bro:type:: BroxygenTest::MyRecord
+
+   :Type: :bro:type:`record`
+
+      f1: :bro:type:`BroxygenTest::TypeAlias`
+
+      f2: :bro:type:`BroxygenTest::OtherTypeAlias`
+
+      f3: :bro:type:`bool`
+
+

testing/btest/doc/autogen-reST-all

@@ -1 +0,0 @@
-@TEST-EXEC: cd $BUILD && make restdoc

testing/btest/doc/autogen-reST-example

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

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

@@ -1,15 +0,0 @@
-# @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 not 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;

testing/btest/doc/broxygen/all_scripts.test

@@ -0,0 +1,10 @@
+# This test is mostly just checking that there's no errors that result
+# from loading all scripts and generated docs for each.
+
+# @TEST-EXEC: bro -X broxygen.config broxygen
+# @TEST-EXEC: btest-diff .stdout
+# @TEST-EXEC: btest-diff .stderr
+
+@TEST-START-FILE broxygen.config
+script	scripts/	*
+@TEST-END-FILE

testing/btest/doc/broxygen/enums.bro

@@ -1,6 +1,10 @@
-# @TEST-EXEC: bro --doc-scripts %INPUT
+# @TEST-EXEC: bro -b -X broxygen.config %INPUT
 # @TEST-EXEC: btest-diff autogen-reST-enums.rst
 
+@TEST-START-FILE broxygen.config
+identifier	autogen-reST-enums.rst	TestEnum*
+@TEST-END-FILE
+
 ## There's tons of ways an enum can look...
 type TestEnum1: enum {
     ## like this
@@ -36,4 +40,4 @@ redef enum TestEnum1 += {
 };
 
 ## this should reference the TestEnum1 type and not a generic "enum" type
-const test_enum_option = ONE &redef;
+const TestEnumVal = ONE &redef;

testing/btest/doc/broxygen/example.bro

@@ -0,0 +1,8 @@
+# @TEST-EXEC: bro -X broxygen.config %INPUT
+# @TEST-EXEC: btest-diff example.rst
+
+@TEST-START-FILE broxygen.config
+script	example.rst	broxygen/example.bro
+@TEST-END-FILE
+
+@load broxygen/example.bro

testing/btest/doc/broxygen/func-params.bro

@@ -1,15 +1,19 @@
-# @TEST-EXEC: bro --doc-scripts %INPUT
+# @TEST-EXEC: bro -b -X broxygen.config %INPUT
 # @TEST-EXEC: btest-diff autogen-reST-func-params.rst
 
+@TEST-START-FILE broxygen.config
+identifier	autogen-reST-func-params.rst	test_func_params*
+@TEST-END-FILE
+
 ## This is a global function declaration.
 ##
 ## i: First param.
 ## j: Second param.
 ##
 ## Returns: A string.
-global test_func: function(i: int, j: int): string;
+global test_func_params_func: function(i: int, j: int): string;
 
-type test_rec: record {
+type test_func_params_rec: record {
 	## This is a record field function.
 	##
 	## i: First param.

testing/btest/doc/broxygen/records.bro

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

testing/btest/doc/broxygen/type-aliases.bro

@@ -0,0 +1,34 @@
+# @TEST-EXEC: bro -b -X broxygen.config %INPUT
+# @TEST-EXEC: btest-diff autogen-reST-type-aliases.rst
+
+@TEST-START-FILE broxygen.config
+identifier	autogen-reST-type-aliases.rst	BroxygenTest::*
+@TEST-END-FILE
+
+module BroxygenTest;
+
+export {
+	## This is just an alias for a builtin type ``bool``.
+	type TypeAlias: bool;
+
+	## This type should get its own comments, not associated w/ TypeAlias.
+	type NotTypeAlias: bool;
+
+	## This cross references ``bool`` in the description of its type
+	## instead of ``TypeAlias`` just because it seems more useful --
+	## one doesn't have to click through the full type alias chain to
+	## find out what the actual type is...
+	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;
+
+	type MyRecord: record {
+		f1: TypeAlias;
+		f2: OtherTypeAlias;
+		f3: bool;
+	};
+}

testing/btest/doc/record-add.bro

@@ -1,7 +1,7 @@
-# @TEST-EXEC: bro --doc-scripts %INPUT
+# @TEST-EXEC: bro -b %INPUT
 
-# When in doc mode, bro will clone declared types (see add_type() in Var.cc)
+# To support documentation of type aliases, Bro clones declared types
-# in order to keep track of the identifier name associated with the new type.
+# (see add_type() in Var.cc) in order to keep track of type names and aliases.
 # This test makes sure that the cloning is done in a way that's compatible
 # with adding fields to a record type -- we want to be sure that cloning
 # a type that contains record types will correctly see field additions to

testing/btest/doc/record-attr-check.bro

@@ -1,4 +1,4 @@
-# @TEST-EXEC: bro --doc-scripts %INPUT
+# @TEST-EXEC: bro -b %INPUT
 
 type Tag: enum {
     SOMETHING