Merge remote-tracking branch 'origin/topic/jsiwek/improve-enum-doc'

* origin/topic/jsiwek/improve-enum-doc:
  Improve auto-generated enum documentation.

Closes #919.

src/ID.cc

@@ -660,8 +660,16 @@ void ID::DescribeReSTShort(ODesc* d) const
 				d->Add(type->AsFuncType()->IsEvent() ? "event" : type_name(t));
 				break;
 
+			case TYPE_ENUM:
+				if ( is_type )
+					d->Add(type_name(t));
+				else
+					d->Add(type->AsEnumType()->Name().c_str());
+				break;
+
 			default:
 				d->Add(type_name(t));
+				break;
 			}
 			}
 

src/Type.cc

@@ -1202,9 +1202,10 @@ bool FileType::DoUnserialize(UnserialInfo* info)
 	return yield != 0;
 	}
 
-EnumType::EnumType()
+EnumType::EnumType(const string& arg_name)
 : BroType(TYPE_ENUM)
 	{
+	name = arg_name;
 	counter = 0;
 	}
 
@@ -1327,6 +1328,13 @@ const char* EnumType::Lookup(bro_int_t value)
 	return 0;
 	}
 
+void EnumType::DescribeReST(ODesc* d) const
+	{
+	d->Add(":bro:type:`");
+	d->Add(name.c_str());
+	d->Add("`");
+	}
+
 void CommentedEnumType::DescribeReST(ODesc* d) const
 	{
 	// create temporary, reverse name map so that enums can be documented

src/Type.h

@@ -497,7 +497,7 @@ protected:
 
 class EnumType : public BroType {
 public:
-	EnumType();
+	EnumType(const string& arg_name);
 	~EnumType();
 
 	// The value of this name is next internal counter value, starting
@@ -513,7 +513,12 @@ public:
 	bro_int_t Lookup(const string& module_name, const char* name);
 	const char* Lookup(bro_int_t value); // Returns 0 if not found
 
+	string Name() const { return name; }
+
+	void DescribeReST(ODesc* d) const;
+
 protected:
+	EnumType() { counter = 0; }
 	DECLARE_SERIAL(EnumType)
 
 	virtual void AddNameInternal(const string& module_name,
@@ -529,11 +534,14 @@ protected:
 	// as a flag to prevent mixing of auto-increment and explicit
 	// enumerator specifications.
 	bro_int_t counter;
+
+	// The name of the enum type is stored for documentation purposes.
+	string name;
 };
 
 class CommentedEnumType: public EnumType {
 public:
-	CommentedEnumType() {}
+	CommentedEnumType(const string& arg_name) : EnumType(arg_name) {}
 	~CommentedEnumType();
 
 	void DescribeReST(ODesc* d) const;

src/parse.y

@@ -131,16 +131,18 @@ const char* cur_enum_elem_id = 0;
 type_decl_list* fake_type_decl_list = 0;
 TypeDecl* last_fake_type_decl = 0;
 
+static ID* cur_decl_type_id = 0;
+
 static void parser_new_enum (void)
 	{
 	/* Starting a new enum definition. */
 	assert(cur_enum_type == NULL);
-	cur_enum_type = new EnumType();
+	cur_enum_type = new EnumType(cur_decl_type_id->Name());
 
 	// For documentation purposes, a separate type object is created
 	// in order to avoid overlap that can be caused by redefs.
 	if ( generate_documentation )
-		cur_enum_type_doc = new CommentedEnumType();
+		cur_enum_type_doc = new CommentedEnumType(cur_decl_type_id->Name());
 	}
 
 static void parser_redef_enum (ID *id)
@@ -158,7 +160,7 @@ static void parser_redef_enum (ID *id)
 		}
 
 	if ( generate_documentation )
-		cur_enum_type_doc = new CommentedEnumType();
+		cur_enum_type_doc = new CommentedEnumType(id->Name());
 	}
 
 static void add_enum_comment (std::list<std::string>* comments)
@@ -1105,9 +1107,10 @@ decl:
 				}
 			}
 
-	|	TOK_TYPE global_id ':' type opt_attr ';'
+	|	TOK_TYPE global_id ':' { cur_decl_type_id = $2; } type opt_attr ';'
 			{
-			add_type($2, $4, $5, 0);
+			cur_decl_type_id = 0;
+			add_type($2, $5, $6, 0);
 
 			if ( generate_documentation )
 				{

testing/btest/Baseline/doc.autogen-reST-enums/autogen-reST-enums.rst

@@ -12,6 +12,12 @@ autogen-reST-enums.bro
 
 Summary
 ~~~~~~~
+Options
+#######
+==================================================================== ======================================================================
+:bro:id:`test_enum_option`: :bro:type:`TestEnum1` :bro:attr:`&redef` this should reference the TestEnum1 type and not a generic "enum" type
+==================================================================== ======================================================================
+
 Types
 #####
 ======================================= ======================================
@@ -30,6 +36,16 @@ Redefinitions
 
 Detailed Interface
 ~~~~~~~~~~~~~~~~~~
+Options
+#######
+.. bro:id:: test_enum_option
+
+   :Type: :bro:type:`TestEnum1`
+   :Attributes: :bro:attr:`&redef`
+   :Default: ``ONE``
+
+   this should reference the TestEnum1 type and not a generic "enum" type
+
 Types
 #####
 .. bro:type:: TestEnum1

testing/btest/doc/autogen-reST-enums.bro

@@ -34,3 +34,6 @@ redef enum TestEnum1 += {
     ## adding another
     FIVE, ##< value
 };
+
+## this should reference the TestEnum1 type and not a generic "enum" type
+const test_enum_option = ONE &redef;