From b1dc5d3a1c94a22aa507b8ced78c45d67d99c6fa Mon Sep 17 00:00:00 2001
From: Jon Siwek <jsiwek@ncsa.illinois.edu>
Date: Mon, 14 Mar 2011 14:49:58 -0500
Subject: [PATCH] Update to auto-generated documentation format.

Comments are now clearly marked.

Enums are now documented in order of their integral value, not
their identifier string.
---
 src/BroDocObj.cc | 23 +++++++++++++----------
 src/Type.cc      | 18 ++++++++++++++----
 2 files changed, 27 insertions(+), 14 deletions(-)

diff --git a/src/BroDocObj.cc b/src/BroDocObj.cc
index a23dec16be..b8f3309f05 100644
--- a/src/BroDocObj.cc
+++ b/src/BroDocObj.cc
@@ -18,16 +18,19 @@ BroDocObj::~BroDocObj()
 
 void BroDocObj::WriteReST(FILE* file) const
     {
-    if ( reST_doc_strings )
-        {
-        std::list<std::string>::const_iterator it;
-        for ( it = reST_doc_strings->begin();
-              it != reST_doc_strings->end(); ++it)
-            fprintf(file, "%s\n", it->c_str());
-        }
-
     ODesc desc;
     desc.SetQuotes(1);
     broID->DescribeReST(&desc);
-    fprintf(file, "%s\n\n", desc.Description());
-    }
+    fprintf(file, "%s\n", desc.Description());
+
+    if ( HasDocumentation() )
+        {
+        fprintf(file, "\t.. bro:comment::\n");
+        std::list<std::string>::const_iterator it;
+        for ( it = reST_doc_strings->begin();
+              it != reST_doc_strings->end(); ++it)
+            fprintf(file, "\t\t%s\n", it->c_str());
+        }
+
+   fprintf(file, "\n");
+   }
diff --git a/src/Type.cc b/src/Type.cc
index ae2d94046c..56d51e98da 100644
--- a/src/Type.cc
+++ b/src/Type.cc
@@ -1067,6 +1067,7 @@ void RecordType::DescribeFieldsReST(ODesc* d, bool func_args) const
 			if ( td->comment )
 				{
 				d->PushIndent();
+				d->Add(".. bro:comment:: ");
 				d->Add(td->comment);
 				d->PopIndent();
 				}
@@ -1345,20 +1346,29 @@ const char* EnumType::Lookup(bro_int_t value)
 
 void EnumType::DescribeReST(ODesc* d) const
 	{
+	// create temporary, reverse name map so that enums can be documented
+	// in ascending order of their actual integral value instead of by name
+	typedef std::map< bro_int_t, const char* > RevNameMap;
+	RevNameMap rev;
+	for ( NameMap::const_iterator it = names.begin(); it != names.end(); ++it )
+		rev[it->second] = it->first;
+
 	d->Add(type_name(Tag()));
 	d->PushIndent();
-	for ( NameMap::const_iterator it = names.begin(); it != names.end(); )
+
+	for ( RevNameMap::const_iterator it = rev.begin(); it != rev.end(); )
 		{
 		d->Add(".. bro:enum:: ");
-		d->Add(it->first);
-		CommentMap::const_iterator cmnt_it = comments.find(it->first);
+		d->Add(it->second);
+		CommentMap::const_iterator cmnt_it = comments.find(it->second);
 		if ( cmnt_it != comments.end() )
 			{
 			d->PushIndent();
+			d->Add(".. bro:comment:: ");
 			d->Add(cmnt_it->second);
 			d->PopIndent();
 			}
-		if ( ++it != names.end() )
+		if ( ++it != rev.end() )
 			d->NL();
 		}
 	}