Changes to add comments per enum or record type field.

src/SerialObj.h

@@ -330,6 +330,29 @@ public:
 		dst = 0;	\
 	}
 
+#define UNSERIALIZE_OPTIONAL_STR_DEL(dst, del)	\
+	{	\
+	bool has_it;	\
+	if ( ! info->s->Read(&has_it, "has_" #dst) )	\
+		{	\
+		delete del;	\
+		return 0;	\
+		}	\
+	\
+	if ( has_it )	\
+		{	\
+		info->s->Read(&dst, 0, "has_" #dst);	\
+		if ( ! dst )	\
+			{	\
+			delete del;	\
+			return 0;	\
+			}	\
+		}	\
+	\
+	else	\
+		dst = 0;	\
+	}
+
 #define UNSERIALIZE_OPTIONAL_STATIC(dst, unserialize, del)	\
 	{	\
 	bool has_it;	\

src/Type.cc

@@ -767,6 +767,7 @@ TypeDecl::TypeDecl(BroType* t, const char* i, attr_list* arg_attrs)
 	type = t;
 	attrs = arg_attrs ? new Attributes(arg_attrs, t) : 0;
 	id = i;
+	comment = 0;
 	}
 
 TypeDecl::~TypeDecl()
@@ -774,6 +775,7 @@ TypeDecl::~TypeDecl()
 	Unref(type);
 	Unref(attrs);
 	delete [] id;
+	if ( comment ) delete [] comment;
 	}
 
 bool TypeDecl::Serialize(SerialInfo* info) const
@@ -783,7 +785,15 @@ bool TypeDecl::Serialize(SerialInfo* info) const
 
 	SERIALIZE_OPTIONAL(attrs);
 
-	return type->Serialize(info) && SERIALIZE(id);
+	if ( ! (type->Serialize(info) && SERIALIZE(id)) )
+		return false;
+
+	if ( generate_documentation )
+		{
+		SERIALIZE_OPTIONAL_STR(comment);
+		}
+
+	return true;
 	}
 
 TypeDecl* TypeDecl::Unserialize(UnserialInfo* info)
@@ -799,6 +809,11 @@ TypeDecl* TypeDecl::Unserialize(UnserialInfo* info)
 		return 0;
 		}
 
+	if ( generate_documentation )
+		{
+		UNSERIALIZE_OPTIONAL_STR_DEL(t->comment, t);
+		}
+
 	return t;
 	}
 
@@ -1048,6 +1063,14 @@ void RecordType::DescribeFieldsReST(ODesc* d, bool func_args) const
 		else
 			td->type->DescribeReST(d);
 
+		if ( ! func_args )
+			if ( td->comment )
+				{
+				d->PushIndent();
+				d->Add(td->comment);
+				d->PopIndent();
+				}
+
 		if ( i + 1 != num_fields )
 			if ( func_args )
 				d->Add(", ");
@@ -1211,6 +1234,12 @@ EnumType::~EnumType()
 	{
 	for ( NameMap::iterator iter = names.begin(); iter != names.end(); ++iter )
 		delete [] iter->first;
+
+	for ( CommentMap::iterator iter = comments.begin(); iter != comments.end(); ++iter )
+		{
+		delete [] iter->first;
+		delete [] iter->second;
+		}
 	}
 
 // Note, we use error() here (not Error()) to include the current script
@@ -1242,6 +1271,12 @@ void EnumType::AddName(const string& module_name, const char* name, bro_int_t va
 	AddNameInternal(module_name, name, val, is_export);
 	}
 
+void EnumType::AddComment(const string& module_name, const char* name, const char* comment)
+	{
+	string fullname = make_full_var_name(module_name.c_str(), name);
+	comments[copy_string(fullname.c_str())] = copy_string(comment);
+	}
+
 void EnumType::AddNameInternal(const string& module_name, const char* name, bro_int_t val, bool is_export)
 	{
 	ID *id;
@@ -1299,6 +1334,13 @@ void EnumType::DescribeReST(ODesc* d) const
 		{
 		d->Add(".. bro:enum:: ");
 		d->Add(it->first);
+		CommentMap::const_iterator cmnt_it = comments.find(it->first);
+		if ( cmnt_it != comments.end() )
+			{
+			d->PushIndent();
+			d->Add(cmnt_it->second);
+			d->PopIndent();
+			}
 		if ( ++it != names.end() )
 			d->NL();
 		}
@@ -1315,6 +1357,10 @@ bool EnumType::DoSerialize(SerialInfo* info) const
 		SERIALIZE(false)) )
 		return false;
 
+	if ( generate_documentation )
+		if ( ! (SERIALIZE((unsigned int) comments.size())) )
+			return false;
+
 	for ( NameMap::const_iterator iter = names.begin();
 	      iter != names.end(); ++iter )
 		{
@@ -1322,6 +1368,14 @@ bool EnumType::DoSerialize(SerialInfo* info) const
 			return false;
 		}
 
+	if ( generate_documentation )
+		for ( CommentMap::const_iterator it = comments.begin();
+			  it != comments.end(); ++ it )
+			{
+			if ( ! SERIALIZE(it->first) || ! SERIALIZE(it->second) )
+				return false;
+			}
+
 	return true;
 	}
 
@@ -1330,6 +1384,7 @@ bool EnumType::DoUnserialize(UnserialInfo* info)
 	DO_UNSERIALIZE(BroType);
 
 	unsigned int len;
+	unsigned int cmnt_len;
 	bool dummy;
 	if ( ! UNSERIALIZE(&counter) ||
 	     ! UNSERIALIZE(&len) ||
@@ -1337,6 +1392,10 @@ bool EnumType::DoUnserialize(UnserialInfo* info)
 	     ! UNSERIALIZE(&dummy) )
 		return false;
 
+	if ( generate_documentation )
+		if ( ! UNSERIALIZE(&cmnt_len) )
+			return false;
+
 	while ( len-- )
 		{
 		const char* name;
@@ -1347,6 +1406,16 @@ bool EnumType::DoUnserialize(UnserialInfo* info)
 		names[name] = val;
 		}
 
+	if ( generate_documentation )
+		while ( cmnt_len-- )
+			{
+			const char* cmnt;
+			const char* name;
+			if ( ! (UNSERIALIZE_STR(&name, 0) && UNSERIALIZE_STR(&cmnt, 0)) )
+				return false;
+			comments[name] = cmnt;
+			}
+
 	return true;
 	}
 

src/Type.h

@@ -384,6 +384,9 @@ public:
 	BroType* type;
 	Attributes* attrs;
 	const char* id;
+
+	// comments are only filled when in "documentation mode"
+	const char* comment;
 };
 
 class RecordField {
@@ -477,6 +480,8 @@ public:
 	// added that aren't likewise explicitly initalized.
 	void AddName(const string& module_name, const char* name, bro_int_t val, bool is_export);
 
+	void AddComment(const string& module_name, const char* name, const char* comment);
+
 	// -1 indicates not found.
 	bro_int_t Lookup(const string& module_name, const char* name);
 	const char* Lookup(bro_int_t value); // Returns 0 if not found
@@ -491,6 +496,10 @@ protected:
 	typedef std::map< const char*, bro_int_t, ltstr > NameMap;
 	NameMap names;
 
+	// comments are only filled when in "documentation mode"
+	typedef std::map< const char*, const char*, ltstr > CommentMap;
+	CommentMap comments;
+
 	// The counter is initialized to 0 and incremented on every implicit
 	// auto-increment name that gets added (thus its > 0 if
 	// auto-increment is used).  Once an explicit value has been