Autodoc framework now tracks script constants

Also, it's starting to attempt to describe more complex types
of initial values.

src/Attr.cc

@@ -59,9 +59,14 @@ void Attr::DescribeReST(ODesc* d) const
 		d->SP();
 		d->Add("=");
 		d->SP();
-		d->Add("``");
+		if ( expr->Type()->Tag() == TYPE_FUNC )
-		expr->Describe(d);
+			d->Add(":bro:type:`func`");
-		d-> Add("``");
+		else
+			{
+			d->Add("``");
+			expr->Describe(d);
+			d-> Add("``");
+			}
 		}
 	}
 

src/BroDoc.cc

@@ -48,6 +48,7 @@ BroDoc::~BroDoc()
 		if ( fclose( reST_file ) )
 			fprintf(stderr, "Failed to close %s", reST_filename.c_str());
 	FreeBroDocObjPtrList(options);
+	FreeBroDocObjPtrList(constants);
 	FreeBroDocObjPtrList(state_vars);
 	FreeBroDocObjPtrList(types);
 	FreeBroDocObjPtrList(notices);
@@ -146,21 +147,21 @@ void BroDoc::WriteDocFile() const
 		WriteToDoc("%s\n", packet_filter.c_str());
 		}
 
-	WriteSectionHeading("Public Interface", '-');
+	WriteInterface("Public Interface", '-', '~', true);
-	WriteBroDocObjList(options, true, "Options", '~');
+	WriteInterface("Private Interface", '-', '~', false);
-	WriteBroDocObjList(state_vars, true, "State Variables", '~');
+	}
-	WriteBroDocObjList(types, true, "Types", '~');
-	WriteBroDocObjList(events, true, "Events", '~');
-	WriteBroDocObjList(functions, true, "Functions", '~');
-	WriteBroDocObjList(redefs, true, "Redefinitions", '~');
 
-	WriteSectionHeading("Private Interface", '-');
+void BroDoc::WriteInterface(const char* heading, char underline,
-	WriteBroDocObjList(options, false, "Options", '~');
+                            char sub, bool isPublic) const
-	WriteBroDocObjList(state_vars, false, "State Variables", '~');
+	{
-	WriteBroDocObjList(types, false, "Types", '~');
+	WriteSectionHeading(heading, underline);
-	WriteBroDocObjList(events, false, "Events", '~');
+	WriteBroDocObjList(options, isPublic, "Options", sub);
-	WriteBroDocObjList(functions, false, "Functions", '~');
+	WriteBroDocObjList(constants, isPublic, "Constants", sub);
-	WriteBroDocObjList(redefs, false, "Redefinitions", '~');
+	WriteBroDocObjList(state_vars, isPublic, "State Variables", sub);
+	WriteBroDocObjList(types, isPublic, "Types", sub);
+	WriteBroDocObjList(events, isPublic, "Events", sub);
+	WriteBroDocObjList(functions, isPublic, "Functions", sub);
+	WriteBroDocObjList(redefs, isPublic, "Redefinitions", sub);
 	}
 
 void BroDoc::WriteStringList(const char* format,

src/BroDoc.h

@@ -35,10 +35,7 @@ public:
 	 * BroDoc's default implementation of this function will care
 	 * about whether declarations made in the Bro script are part of
 	 * the public versus private interface (whether things are declared in
-	 * the export section).  Things in a script's export section make it
+	 * the export section).
-	 * into the reST output regardless of whether they have ## comments
-	 * but things outside the export section are only output into the reST
-	 * if they have ## comments.
 	 */
 	virtual void WriteDocFile() const;
 
@@ -93,6 +90,16 @@ public:
 	 */
 	void AddOption(const BroDocObj* o) { options.push_back(o); }
 
+	/**
+	 * Schedules documentation of a script constant.  An option is
+	 * defined as any variable in the script that is declared 'const'
+	 * and does *not* have the '&redef' attribute.
+	 * @param o A pointer to a BroDocObj which contains the internal
+	 *        Bro language representation of the script constant and
+	 *        also any associated comments about it.
+	 */
+	void AddConstant(const BroDocObj* o) { constants.push_back(o); }
+
 	/**
 	 * Schedules documentation of a script state variable.  A state variable
 	 * is defined as any variable in the script that is declared 'global'
@@ -167,6 +174,7 @@ protected:
 	std::list<std::string> port_analysis;
 
 	std::list<const BroDocObj*> options;
+	std::list<const BroDocObj*> constants;
 	std::list<const BroDocObj*> state_vars;
 	std::list<const BroDocObj*> types;
 	std::list<const BroDocObj*> notices;
@@ -235,6 +243,19 @@ protected:
 	 *        within the reST document
 	 */
 	void WriteSectionHeading(const char* heading, char underline) const;
+
+	/**
+	 * Writes out the reST for either the script's public or private interface
+	 * @param heading The title of the interfaces section heading
+	 * @param underline The underline character to use for the interface
+	 *        section
+	 * @param subunderline The underline character to use for interface
+	 *        sub-sections
+	 * @param isPublic Whether to write out the public or private script
+	 *        interface
+	 */
+	void WriteInterface(const char* heading, char underline, char subunderline,
+	                    bool isPublic) const;
 private:
 
 	/**

src/ID.cc

@@ -651,12 +651,26 @@ void ID::DescribeReST(ODesc* d, bool is_role) const
 		}
 
 	if ( val && type &&
-		 type->InternalType() != TYPE_INTERNAL_OTHER &&
+		 type->Tag() != TYPE_FUNC &&
 		 type->InternalType() != TYPE_INTERNAL_VOID )
 		{
-		d->Add(":Init: ");
+		if ( type->InternalType() == TYPE_INTERNAL_OTHER )
-		val->DescribeReST(d);
+			{
-		d->NL();
+			d->Add(":Init:");
+			d->NL();
+			d->NL();
+			d->Add("::");
+			d->NL();
+			d->PushIndent();
+			val->DescribeReST(d);
+			d->PopIndent();
+			}
+		else
+			{
+			d->Add(":Init: ");
+			val->DescribeReST(d);
+			d->NL();
+			}
 		}
 	}
 

src/Val.cc

@@ -576,9 +576,14 @@ void Val::Describe(ODesc* d) const
 
 void Val::DescribeReST(ODesc* d) const
 	{
-	d->Add("``");
+	if ( type->InternalType() == TYPE_INTERNAL_OTHER )
-	ValDescribeReST(d);
+		Describe(d);
-	d->Add("``");
+	else
+		{
+		d->Add("``");
+		ValDescribeReST(d);
+		d->Add("``");
+		}
 	}
 
 void Val::ValDescribe(ODesc* d) const

src/parse.y

@@ -991,6 +991,9 @@ decl:
 				if ( $2->FindAttr(ATTR_REDEF) )
 					current_reST_doc->AddOption(
 						new BroDocObj($2, reST_doc_comments));
+				else
+					current_reST_doc->AddConstant(
+						new BroDocObj($2, reST_doc_comments));
 			}
 
 	|	TOK_REDEF global_id opt_type init_class opt_init opt_attr ';'