Fix generated script docs displaying functions twice.

A function prototype can be declared separately from where it's defined;
the doc framework should now recognize them as the same and combine
reST documentation associated with either case if both are present.

src/BroDoc.cc

@@ -180,7 +180,7 @@ void BroDoc::WriteStringList(const char* format,
 	WriteToDoc(last_format, last->c_str());
 	}
 
-void BroDoc::WriteBroDocObjList(const std::list<const BroDocObj*>& l,
+void BroDoc::WriteBroDocObjList(const BroDocObjList& l,
                                 bool wantPublic,
                                 const char* heading,
                                 char underline) const
@@ -205,16 +205,37 @@ void BroDoc::WriteBroDocObjList(const std::list<const BroDocObj*>& l,
 		}
 	}
 
-void BroDoc::WriteBroDocObjList(const std::list<const BroDocObj*>& l,
+void BroDoc::WriteBroDocObjList(const BroDocObjMap& m,
+                                bool wantPublic,
+                                const char* heading,
+                                char underline) const
+	{
+	BroDocObjMap::const_iterator it;
+	BroDocObjList l;
+	for ( it = m.begin(); it != m.end(); ++it ) l.push_back(it->second);
+	WriteBroDocObjList(l, wantPublic, heading, underline);
+	}
+
+void BroDoc::WriteBroDocObjList(const BroDocObjList& l,
                                 const char* heading,
                                 char underline) const
 	{
 	WriteSectionHeading(heading, underline);
-	std::list<const BroDocObj*>::const_iterator it;
+	BroDocObjList::const_iterator it;
 	for ( it = l.begin(); it != l.end(); ++it )
 		(*it)->WriteReST(reST_file);
 	}
 
+void BroDoc::WriteBroDocObjList(const BroDocObjMap& m,
+                                const char* heading,
+                                char underline) const
+	{
+	BroDocObjMap::const_iterator it;
+	BroDocObjList l;
+	for ( it = m.begin(); it != m.end(); ++it ) l.push_back(it->second);
+	WriteBroDocObjList(l, heading, underline);
+	}
+
 void BroDoc::WriteToDoc(const char* format, ...) const
 	{
 	va_list argp;
@@ -232,10 +253,25 @@ void BroDoc::WriteSectionHeading(const char* heading, char underline) const
 	WriteToDoc("\n");
 	}
 
-void BroDoc::FreeBroDocObjPtrList(std::list<const BroDocObj*>& l)
+void BroDoc::FreeBroDocObjPtrList(BroDocObjList& l)
 	{
-	std::list<const BroDocObj*>::iterator it;
+	for ( BroDocObjList::const_iterator it = l.begin(); it != l.end(); ++it )
-	for ( it = l.begin(); it != l.end(); ++it )
 		delete *it;
 	l.clear();
 	}
+
+void BroDoc::FreeBroDocObjPtrList(BroDocObjMap& l)
+	{
+	for ( BroDocObjMap::const_iterator it = l.begin(); it != l.end(); ++it )
+		delete it->second;
+	l.clear();
+	}
+
+void BroDoc::AddFunction(BroDocObj* o)
+	{
+	BroDocObjMap::const_iterator it = functions.find(o->Name());
+	if ( it == functions.end() )
+		functions[o->Name()] = o;
+	else
+		functions[o->Name()]->Combine(o);
+	}

src/BroDoc.h

@@ -139,7 +139,7 @@ public:
 	 *        Bro language representation of the script function and
 	 *        also any associated comments about it.
 	 */
-	void AddFunction(const BroDocObj* o) { functions.push_back(o); }
+	void AddFunction(BroDocObj* o);
 
    /**
 	 * Schedules documentation of a redef done by the script
@@ -173,14 +173,17 @@ protected:
 	std::list<std::string> imports;
 	std::list<std::string> port_analysis;
 
-	std::list<const BroDocObj*> options;
+	typedef std::list<const BroDocObj*> BroDocObjList;
-	std::list<const BroDocObj*> constants;
+	typedef std::map<std::string, BroDocObj*> BroDocObjMap;
-	std::list<const BroDocObj*> state_vars;
+
-	std::list<const BroDocObj*> types;
+	BroDocObjList options;
-	std::list<const BroDocObj*> notices;
+	BroDocObjList constants;
-	std::list<const BroDocObj*> events;
+	BroDocObjList state_vars;
-	std::list<const BroDocObj*> functions;
+	BroDocObjList types;
-	std::list<const BroDocObj*> redefs;
+	BroDocObjList notices;
+	BroDocObjList events;
+	BroDocObjMap functions;
+	BroDocObjList redefs;
 
 	/**
 	 * Writes out a list of strings to the reST document.
@@ -213,7 +216,17 @@ protected:
 	 * @param underline The character to use to underline the reST
 	 *        section heading.
 	 */
-	void WriteBroDocObjList(const std::list<const BroDocObj*>& l,
+	void WriteBroDocObjList(const BroDocObjList& l,
+	                        bool wantPublic,
+	                        const char* heading,
+	                        char underline) const;
+
+	/**
+	 * Wraps the BroDocObjMap into a BroDocObjList and the writes that list
+	 * to the reST document
+	 * @see WriteBroDocObjList(const BroDocObjList&, bool, const char*, char)
+	 */
+	void WriteBroDocObjList(const BroDocObjMap& m,
 	                        bool wantPublic,
 	                        const char* heading,
 	                        char underline) const;
@@ -225,7 +238,16 @@ protected:
 	 * @param underline The character to use to underline the reST
 	 *        section heading.
 	 */
-	void WriteBroDocObjList(const std::list<const BroDocObj*>& l,
+	void WriteBroDocObjList(const BroDocObjList& l,
+	                        const char* heading,
+	                        char underline) const;
+
+	/**
+	 * Wraps the BroDocObjMap into a BroDocObjList and the writes that list
+	 * to the reST document
+	 * @see WriteBroDocObjList(const BroDocObjList&, const char*, char)
+	 */
+	void WriteBroDocObjList(const BroDocObjMap& m,
 	                        const char* heading,
 	                        char underline) const;
 
@@ -262,7 +284,8 @@ private:
 	 * Frees memory allocated to BroDocObj's objects in a given list.
 	 * @param a reference to a list of BroDocObj pointers
 	 */
-	void FreeBroDocObjPtrList(std::list<const BroDocObj*>& l);
+	void FreeBroDocObjPtrList(BroDocObjList& l);
+	void FreeBroDocObjPtrList(BroDocObjMap& l);
 
 	static bool IsPublicAPI(const BroDocObj* o) { return o->IsPublicAPI(); }
 	static bool IsPrivateAPI(const BroDocObj* o) { return ! o->IsPublicAPI(); }

src/BroDocObj.cc

@@ -16,7 +16,7 @@ BroDocObj::BroDocObj(const ID* id, std::list<std::string>*& reST,
 
 BroDocObj::~BroDocObj()
 	{
-	delete reST_doc_strings;
+	if ( reST_doc_strings ) delete reST_doc_strings;
 	if ( is_fake_id ) delete broID;
 	}
 
@@ -50,3 +50,17 @@ bool BroDocObj::IsPublicAPI() const
 	return (broID->Scope() == SCOPE_GLOBAL) ||
 	       (broID->Scope() == SCOPE_MODULE && broID->IsExport());
 	}
+
+void BroDocObj::Combine(const BroDocObj* o)
+	{
+	if ( o->reST_doc_strings )
+		{
+		if ( ! reST_doc_strings )
+			reST_doc_strings = new std::list<std::string>();
+
+		reST_doc_strings->splice(reST_doc_strings->end(),
+		                         *(o->reST_doc_strings));
+		}
+
+	delete o;
+	}

src/BroDocObj.h

@@ -66,6 +66,18 @@ public:
 	 */
 	void SetRole(bool b) { use_role = b; }
 
+	/**
+	 * Append any reST documentation strings in a given BroDocObj to this
+	 * object's list and then delete the given BroDocObj
+	 * @param o a pointer to a BroDocObj to subsume
+	 */
+	void Combine(const BroDocObj* o);
+
+	/**
+	 * @return the name of the wrapped identifier
+	 */
+	const char* Name() const { return broID->Name(); }
+
 protected:
 	std::list<std::string>* reST_doc_strings;
 	const ID* broID;