Allow Broxygen markup "##<" for more general use.

doc/scripts/example.bro

@@ -1,5 +1,5 @@
-##! This is an example script that demonstrates how to document.  Comments
+##! This is an example script that demonstrates documentation features.
-##! of the form ``##!`` are for the script summary.  The contents of
+##! 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.
@@ -22,8 +22,8 @@
 # field comments, it's necessary to disambiguate the field with
 # which a comment associates: e.g. "##<" can be used on the same line
 # as a field to signify the comment relates to it and not the
-# following field.  "##<" is not meant for general use, just
+# following field. "##<" can also be used more generally in any
-# record/enum fields.
+# 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
@@ -151,7 +151,7 @@ export {
     const an_option: set[addr, addr, string] &redef;
 
     # default initialization will be self-documenting
-    const option_with_init = 0.01 secs &redef;
+    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

src/BroDocObj.cc

@@ -4,9 +4,12 @@
 #include "ID.h"
 #include "BroDocObj.h"
 
+BroDocObj* BroDocObj::last = 0;
+
 BroDocObj::BroDocObj(const ID* id, std::list<std::string>*& reST,
 			bool is_fake)
 	{
+	last = this;
 	broID = id;
 	reST_doc_strings = reST;
 	reST = 0;

src/BroDocObj.h

@@ -103,6 +103,20 @@ public:
 	 */
 	int LongestShortDescLen() const;
 
+	/**
+	 * Adds a reST documentation string to this BroDocObj's list.
+	 * @param s the documentation string to append.
+	 */
+	void AddDocString(const std::string& s)
+		{
+		if ( ! reST_doc_strings )
+			reST_doc_strings = new std::list<std::string>();
+		reST_doc_strings->push_back(s);
+		FormulateShortDesc();
+		}
+
+	static BroDocObj* last;
+
 protected:
 	std::list<std::string>* reST_doc_strings;
 	std::list<std::string> short_desc;

src/scan.l

@@ -201,6 +201,11 @@ ESCSEQ	(\\([^\n]|[0-7]+|x[[:xdigit:]]+))
 		}
 }
 
+##<.* {
+	if ( generate_documentation && BroDocObj::last )
+		BroDocObj::last->AddDocString(canon_doc_comment(yytext + 3));
+}
+
 ##.* {
 	if ( generate_documentation && (yytext[2] != '#') )
 		{

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

@@ -7,8 +7,8 @@ example.bro
 
 Overview
 --------
-This is an example script that demonstrates how to document.  Comments
+This is an example script that demonstrates documentation features.
-of the form ``##!`` are for the script summary.  The contents of
+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.
@@ -34,7 +34,7 @@ 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`
+:bro:id:`Example::option_with_init`: :bro:type:`interval` :bro:attr:`&redef` More docs can be added here.
 ============================================================================ ======================================
 
 State Variables
@@ -128,6 +128,8 @@ Options
    :Attributes: :bro:attr:`&redef`
    :Default: ``10.0 msecs``
 
+   More docs can be added here.
+
 State Variables
 ~~~~~~~~~~~~~~~
 .. bro:id:: Example::a_var