Fixes for declared type ID tracking & adding DescribeReST()'s

Changed BroType to track a char* instead of an ID* that represents
the declared type's identifier.  It was also necessary to serialize
this information or else it can be lost (e.g. FieldDecl's in RecordType
always seem to get serialized at some point).

DescribeReST() functions added to many classes to get the output
closer to being reST compatible; still needs tweaking for Sphinx
(reST->HTML) compatibility.

src/Attr.cc

@@ -49,6 +49,17 @@ void Attr::Describe(ODesc* d) const
 		}
 	}
 
+void Attr::DescribeReST(ODesc* d) const
+	{
+	d->Add(".. bro:attr:: ");
+	AddTag(d);
+	if ( expr )
+		{
+		d->Add("=");
+		expr->Describe(d);
+		}
+	}
+
 void Attr::AddTag(ODesc* d) const
 	{
 	if ( d->IsBinary() )
@@ -161,6 +172,15 @@ void Attributes::Describe(ODesc* d) const
 		}
 	}
 
+void Attributes::DescribeReST(ODesc* d) const
+	{
+	loop_over_list(*attrs, i)
+		{
+		d->NL();
+		(*attrs)[i]->DescribeReST(d);
+		}
+	}
+
 void Attributes::CheckAttr(Attr* a)
 	{
 	switch ( a->Tag() ) {

src/Attr.h

@@ -51,6 +51,7 @@ public:
 		{ return tag == ATTR_REDEF || tag == ATTR_OPTIONAL; }
 
 	void Describe(ODesc* d) const;
+	void DescribeReST(ODesc* d) const;
 
 protected:
 	void AddTag(ODesc* d) const;
@@ -73,6 +74,7 @@ public:
 	void RemoveAttr(attr_tag t);
 
 	void Describe(ODesc* d) const;
+	void DescribeReST(ODesc* d) const;
 
 	attr_list* Attrs()	{ return attrs; }
 

src/BroDocObj.cc

@@ -27,6 +27,7 @@ void BroDocObj::WriteReST(FILE* file) const
         }
 
     ODesc desc;
-    broID->DescribeExtended(&desc);
+    desc.SetQuotes(1);
-    fprintf(file, "%s\n", desc.Description());
+    broID->DescribeReST(&desc);
+    fprintf(file, "%s\n\n", desc.Description());
     }

src/ID.cc

@@ -607,6 +607,41 @@ void ID::DescribeExtended(ODesc* d) const
 		}
 	}
 
+void ID::DescribeReST(ODesc* d) const
+	{
+	d->Add(".. bro:id:: ");
+	d->Add(name);
+	d->PushIndent();
+
+	if ( type )
+		{
+		d->Add(".. bro:type:: ");
+		if ( ! is_type && type->GetTypeID() )
+			{
+			d->Add("`");
+			d->Add(type->GetTypeID());
+			d->Add("`");
+			}
+		else
+			type->DescribeReST(d);
+		}
+
+	if ( attrs )
+		{
+		attrs->DescribeReST(d);
+		}
+
+	if ( val && type &&
+		 type->InternalType() != TYPE_INTERNAL_OTHER &&
+		 type->InternalType() != TYPE_INTERNAL_VOID )
+		{
+		d->NL();
+		d->Add(".. bro:val:: ");
+		val->DescribeReST(d);
+		}
+
+	}
+
 #ifdef DEBUG
 void ID::UpdateValID()
 	{

src/ID.h

@@ -84,6 +84,8 @@ public:
 	void Describe(ODesc* d) const;
 	// Adds type and value to description.
 	void DescribeExtended(ODesc* d) const;
+	// Produces a description that's reST-ready
+	void DescribeReST(ODesc* d) const;
 
 	bool Serialize(SerialInfo* info) const;
 	static ID* Unserialize(UnserialInfo* info);

src/Type.cc

@@ -108,6 +108,11 @@ BroType::BroType(TypeTag t, bool arg_base_type)
 
 	}
 
+BroType::~BroType()
+	{
+	if ( type_id ) delete [] type_id;
+	}
+
 int BroType::MatchesIndex(ListExpr*& /* index */) const
 	{
 	return DOES_NOT_MATCH_INDEX;
@@ -142,6 +147,11 @@ void BroType::Describe(ODesc* d) const
 		}
 	}
 
+void BroType::DescribeReST(ODesc* d) const
+	{
+	Describe(d);
+	}
+
 void BroType::SetError()
 	{
 	tag = TYPE_ERROR;
@@ -234,6 +244,11 @@ bool BroType::DoSerialize(SerialInfo* info) const
 	void* null = NULL;
 	SERIALIZE(null);
 
+	if ( generate_documentation )
+		{
+		SERIALIZE_OPTIONAL_STR(type_id);
+		}
+
 	info->s->WriteCloseTag("Type");
 
 	return true;
@@ -264,6 +279,11 @@ bool BroType::DoUnserialize(UnserialInfo* info)
 	// attributes_type" for backwards compatibility.
 	UNSERIALIZE_OPTIONAL(not_used_either, BroType::Unserialize(info, TYPE_RECORD));
 
+	if ( generate_documentation )
+		{
+		UNSERIALIZE_OPTIONAL_STR(type_id);
+		}
+
 	return true;
 	}
 
@@ -417,6 +437,44 @@ void IndexType::Describe(ODesc* d) const
 		}
 	}
 
+void IndexType::DescribeReST(ODesc* d) const
+	{
+	if ( IsSet() )
+		d->Add("set");
+	else
+		d->Add(type_name(Tag()));
+
+	d->Add("[");
+	loop_over_list(*IndexTypes(), i)
+		{
+		if ( i > 0 )
+			d->Add(",");
+		const BroType* t = (*IndexTypes())[i];
+		if ( t->GetTypeID() )
+			{
+			d->Add("`");
+			d->Add(t->GetTypeID());
+			d->Add("`");
+			}
+		else
+			t->DescribeReST(d);
+		}
+	d->Add("]");
+
+	if ( yield_type )
+		{
+		d->Add(" of ");
+		if ( yield_type->GetTypeID() )
+			{
+			d->Add("`");
+			d->Add(yield_type->GetTypeID());
+			d->Add("`");
+			}
+		else
+			yield_type->DescribeReST(d);
+		}
+	}
+
 bool IndexType::IsSubNetIndex() const
 	{
 	const type_list* types = indices->Types();
@@ -651,6 +709,26 @@ void FuncType::Describe(ODesc* d) const
 		}
 	}
 
+void FuncType::DescribeReST(ODesc* d) const
+	{
+	d->Add(is_event ? "event" : "function");
+	d->Add("(");
+	args->DescribeFieldsReST(d, true);
+	d->Add(")");
+	if ( yield )
+		{
+		d->AddSP(" :");
+		if ( yield->GetTypeID() )
+			{
+			d->Add("`");
+			d->Add(yield->GetTypeID());
+			d->Add("`");
+			}
+		else
+			yield->DescribeReST(d);
+		}
+	}
+
 IMPLEMENT_SERIAL(FuncType, SER_FUNC_TYPE);
 
 bool FuncType::DoSerialize(SerialInfo* info) const
@@ -902,6 +980,12 @@ void RecordType::Describe(ODesc* d) const
 		}
 	}
 
+void RecordType::DescribeReST(ODesc* d) const
+	{
+	d->Add("record");
+	DescribeFieldsReST(d, false);
+	}
+
 void RecordType::DescribeFields(ODesc* d) const
 	{
 	if ( d->IsReadable() )
@@ -941,6 +1025,37 @@ void RecordType::DescribeFields(ODesc* d) const
 		}
 	}
 
+void RecordType::DescribeFieldsReST(ODesc* d, bool func_args) const
+	{
+	if ( ! func_args )
+		d->PushIndent();
+
+	for ( int i = 0; i < num_fields; ++i )
+		{
+		const TypeDecl* td = FieldDecl(i);
+		if ( ! func_args )
+			d->Add(":bro:field: ");
+
+		d->Add(td->id);
+		d->Add(": ");
+		d->Add(":bro:type: ");
+		if ( td->type->GetTypeID() )
+			{
+			d->Add("`");
+			d->Add(td->type->GetTypeID());
+			d->Add("`");
+			}
+		else
+			td->type->DescribeReST(d);
+
+		if ( i + 1 != num_fields )
+			if ( func_args )
+				d->Add(", ");
+			else
+				d->NL();
+		}
+	}
+
 IMPLEMENT_SERIAL(RecordType, SER_RECORD_TYPE)
 
 bool RecordType::DoSerialize(SerialInfo* info) const
@@ -1176,6 +1291,19 @@ const char* EnumType::Lookup(bro_int_t value)
 	return 0;
 	}
 
+void EnumType::DescribeReST(ODesc* d) const
+	{
+	d->Add(type_name(Tag()));
+	d->PushIndent();
+	for ( NameMap::const_iterator it = names.begin(); it != names.end(); )
+		{
+		d->Add(".. bro:enum:: ");
+		d->Add(it->first);
+		if ( ++it != names.end() )
+			d->NL();
+		}
+	}
+
 IMPLEMENT_SERIAL(EnumType, SER_ENUM_TYPE);
 
 bool EnumType::DoSerialize(SerialInfo* info) const

src/Type.h

@@ -67,6 +67,7 @@ const int MATCHES_INDEX_VECTOR = 2;
 class BroType : public BroObj {
 public:
 	BroType(TypeTag tag, bool base_type = false);
+	~BroType();
 
 	TypeTag Tag() const		{ return tag; }
 	InternalTypeTag InternalType() const	{ return internal_tag; }
@@ -200,14 +201,15 @@ public:
 	BroType* Ref()		{ ::Ref(this); return this; }
 
 	virtual void Describe(ODesc* d) const;
+	virtual void DescribeReST(ODesc* d) const;
 
 	virtual unsigned MemoryAllocation() const;
 
 	bool Serialize(SerialInfo* info) const;
 	static BroType* Unserialize(UnserialInfo* info, TypeTag want = TYPE_ANY);
 
-	void SetTypeID(const ID* id) { type_id = id; }
+	void SetTypeID(const char* id) { type_id = id; }
-	const ID* GetTypeID() const { return type_id; }
+	const char* GetTypeID() const { return type_id; }
 
 protected:
 	BroType()	{ type_id = 0; }
@@ -224,7 +226,7 @@ private:
 
 	// This type_id field is only used by the documentation framework to
 	// track the names of declared types.
-	const ID* type_id;
+	const char* type_id;
 };
 
 class TypeList : public BroType {
@@ -280,6 +282,7 @@ public:
 	BroType* YieldType();
 
 	void Describe(ODesc* d) const;
+	void DescribeReST(ODesc* d) const;
 
 	// Returns true if this table is solely indexed by subnet.
 	bool IsSubNetIndex() const;
@@ -354,6 +357,7 @@ public:
 	ID* GetReturnValueID() const;
 
 	void Describe(ODesc* d) const;
+	void DescribeReST(ODesc* d) const;
 
 protected:
 	FuncType()	{ args = 0; arg_types = 0; yield = 0; return_value = 0; }
@@ -417,7 +421,9 @@ public:
 	int NumFields() const			{ return num_fields; }
 
 	void Describe(ODesc* d) const;
+	void DescribeReST(ODesc* d) const;
 	void DescribeFields(ODesc* d) const;
+	void DescribeFieldsReST(ODesc* d, bool func_args) const;
 
 protected:
 	RecordType() { fields = 0; base = 0; types = 0; }
@@ -475,6 +481,8 @@ public:
 	bro_int_t Lookup(const string& module_name, const char* name);
 	const char* Lookup(bro_int_t value); // Returns 0 if not found
 
+	void DescribeReST(ODesc* d) const;
+
 protected:
 	DECLARE_SERIAL(EnumType)
 

src/Val.cc

@@ -574,6 +574,11 @@ void Val::Describe(ODesc* d) const
 		Val::ValDescribe(d);
 	}
 
+void Val::DescribeReST(ODesc* d) const
+	{
+	ValDescribeReST(d);
+	}
+
 void Val::ValDescribe(ODesc* d) const
 	{
 	if ( d->IsReadable() && type->Tag() == TYPE_BOOL )
@@ -615,6 +620,11 @@ void Val::ValDescribe(ODesc* d) const
 	}
 	}
 
+void Val::ValDescribeReST(ODesc* d) const
+	{
+	ValDescribe(d);
+	}
+
 MutableVal::~MutableVal()
 	{
 	for ( list<ID*>::iterator i = aliases.begin(); i != aliases.end(); ++i )

src/Val.h

@@ -313,6 +313,7 @@ public:
 		}
 
 	void Describe(ODesc* d) const;
+	void DescribeReST(ODesc* d) const;
 
 	bool Serialize(SerialInfo* info) const;
 	static Val* Unserialize(UnserialInfo* info, TypeTag type = TYPE_ANY)
@@ -347,6 +348,7 @@ protected:
 		}
 
 	virtual void ValDescribe(ODesc* d) const;
+	virtual void ValDescribeReST(ODesc* d) const;
 
 	Val(TypeTag t)
 		{

src/Var.cc

@@ -249,7 +249,7 @@ void add_type(ID* id, BroType* t, attr_list* attr, int /* is_event */)
 
 		delete [] data;
 
-		tnew->SetTypeID(id);
+		tnew->SetTypeID(copy_string(id->Name()));
 		}
 
 	id->SetType(tnew);