Merge remote branch 'origin/fastpath'

* origin/fastpath:
  Enable warnings for malformed Broxygen xref roles.
  Broxygen fix for function parameter recognition; better than 80b2451.
  Allow Broxygen markup "##<" for more general use.

CHANGES

@@ -1,4 +1,13 @@
 
+2.0-beta-121 | 2011-12-18 15:10:15 -0800
+
+  * Enable warnings for malformed Broxygen xref roles. (Jon Siwek)
+
+  * Fix Broxygen confusing scoped IDs at start of line as function
+    parameter. (Jon Siwek)
+
+  * Allow Broxygen markup "##<" for more general use. (Jon Siwek)
+    
 2.0-beta-116 | 2011-12-16 02:38:27 -0800
 
   * Cleanup some misc Broxygen css/js stuff. (Jon Siwek)
@@ -28,9 +37,6 @@
   * Fixed bug that was causing the malware hash registry script to
     break. (Seth Hall)
 
-  * Fix Broxygen confusing scoped IDs at start of line as function
-    parameter. (Jon Siwek)
-
   * Remove remnant of libmagic optionality. (Jon Siwek)
 
 2.0-beta-98 | 2011-12-07 08:12:08 -0800

VERSION

@@ -1 +1 @@
-2.0-beta-116
+2.0-beta-121

doc/ext/bro.py

@@ -257,6 +257,9 @@ class BroDomain(Domain):
                                         objects[objtype, target],
                                         objtype + '-' + target,
                                         contnode, target + ' ' + objtype)
+                else:
+                    self.env.warn(fromdocname,
+                        'unknown target for ":bro:%s:`%s`"' % (typ, target))
 
     def get_objects(self):
         for (typ, name), docname in self.data['objects'].iteritems():

doc/scripts/example.bro

@@ -1,5 +1,5 @@
-##! This is an example script that demonstrates how to document.  Comments
-##! of the form ``##!`` are for the script summary.  The contents of
+##! 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.
@@ -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
-# record/enum fields.
+# following field. "##<" can also be used more generally in any
+# 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

@@ -167,7 +167,7 @@ ESCSEQ	(\\([^\n]|[0-7]+|x[[:xdigit:]]+))
 	return TOK_POST_DOC;
 }
 
-<DOC>##{OWS}{ID}:[^:].* {
+<DOC>##{OWS}{ID}:{WS}.* {
 	const char* id_start = skip_whitespace(yytext + 2);
 	yylval.str = copy_string(canon_doc_func_param(id_start).c_str());
 	return TOK_DOC;
@@ -181,7 +181,7 @@ ESCSEQ	(\\([^\n]|[0-7]+|x[[:xdigit:]]+))
 		}
 }
 
-##{OWS}{ID}:[^:].* {
+##{OWS}{ID}:{WS}.* {
 	if ( generate_documentation )
 		{
 		// Comment is documenting either a function parameter or return type,
@@ -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
-of the form ``##!`` are for the script summary.  The contents of
+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.
@@ -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