Minor Broxygen improvements, addresses BIT-1098.

- Internals: move type alias table to private static BroType member.

- Sphinx extension: now uses absolute path to bro binary.

- reST ouput formatting: remove "param" from function desriptions
  and change package overview docs so script link+summaries render
  consistently.

doc/conf.py.in

@@ -35,6 +35,7 @@ btest_tests="doc/sphinx"
 
 # ----- Begin of Broxygen configuration. -----
 extensions += ["broxygen"]
+bro_binary = os.path.abspath("@CMAKE_SOURCE_DIR@/build/src/bro")
 broxygen_cache="@BROXYGEN_CACHE_DIR@"
 os.environ["BROPATH"] = "@BROPATH@"
 os.environ["BROMAGIC"] = "@BROMAGIC@"

doc/ext/broxygen.py

@@ -114,7 +114,12 @@ def build_target(env, target):
     import os
     import subprocess
 
-    bro_cmd = "bro -X {0} broxygen".format(target.config_file)
+    path_to_bro = env.config.bro_binary
+
+    if not path_to_bro:
+        raise SphinxError("'bro' not set in sphinx config file (path to bro)")
+
+    bro_cmd = "{0} -X {1} broxygen".format(path_to_bro, target.config_file)
     cwd = os.getcwd()
     os.chdir(os.path.dirname(target.config_file))
 
@@ -307,5 +312,6 @@ def setup(app):
     global App
     App = app
     app.add_domain(BroxygenDomain)
+    app.add_config_value("bro_binary", None, "env")
     app.add_config_value("broxygen_cache", None, "env")
     app.connect("env-get-outdated", env_get_outdated_hook)

src/Type.cc

@@ -15,6 +15,8 @@
 #include <list>
 #include <map>
 
+BroType::TypeAliasMap BroType::type_aliases;
+
 // Note: This function must be thread-safe.
 const char* type_name(TypeTag t)
 	{
@@ -1183,8 +1185,7 @@ void RecordType::DescribeFieldsReST(ODesc* d, bool func_args) const
 		     field_from_script != type_from_script )
 			{
 			d->PushIndent();
-			d->Add(fmt("(from ``redef`` in :doc:`/scripts/%s`)",
-			           field_from_script.c_str()));
+			d->Add(broxygen::redef_indication(field_from_script).c_str());
 			d->PopIndent();
 			}
 
@@ -1455,7 +1456,7 @@ void EnumType::CheckAndAddName(const string& module_name, const char* name,
 
 	AddNameInternal(module_name, name, val, is_export);
 
-	set<BroType*> types = type_aliases[GetName()];
+	set<BroType*> types = BroType::GetAliases(GetName());
 	set<BroType*>::const_iterator it;
 
 	for ( it = types.begin(); it != types.end(); ++it )
@@ -1541,8 +1542,7 @@ void EnumType::DescribeReST(ODesc* d, bool roles_only) const
 			{
 			d->NL();
 			d->PushIndent();
-			d->Add(fmt("(from ``redef`` in :doc:`/scripts/%s`)",
-			           enum_from_script.c_str()));
+			d->Add(broxygen::redef_indication(enum_from_script).c_str());
 			d->PopIndent();
 			}
 

src/Type.h

@@ -245,6 +245,14 @@ public:
 	void SetName(const string& arg_name) { name = arg_name; }
 	string GetName() const { return name; }
 
+	typedef std::map<std::string, std::set<BroType*> > TypeAliasMap;
+
+	static std::set<BroType*> GetAliases(const std::string& type_name)
+		{ return BroType::type_aliases[type_name]; }
+
+	static void AddAlias(const std::string type_name, BroType* type)
+		{ BroType::type_aliases[type_name].insert(type); }
+
 protected:
 	BroType()	{ }
 
@@ -258,6 +266,8 @@ private:
 	bool is_network_order;
 	bool base_type;
 	string name;
+
+	static TypeAliasMap type_aliases;
 };
 
 class TypeList : public BroType {
@@ -580,9 +590,6 @@ protected:
 	BroType* yield_type;
 };
 
-typedef std::map<std::string, std::set<BroType*> > TypeAliasMap;
-extern TypeAliasMap type_aliases;
-
 extern OpaqueType* md5_type;
 extern OpaqueType* sha1_type;
 extern OpaqueType* sha256_type;

src/Var.cc

@@ -273,10 +273,10 @@ void add_type(ID* id, BroType* t, attr_list* attr)
 		// Clone the type to preserve type name aliasing.
 		tnew = t->Clone();
 
-	type_aliases[new_type_name].insert(tnew);
+	BroType::AddAlias(new_type_name, tnew);
 
 	if ( new_type_name != old_type_name && ! old_type_name.empty() )
-		type_aliases[old_type_name].insert(tnew);
+		BroType::AddAlias(old_type_name, tnew);
 
 	tnew->SetName(id->Name());
 

src/broxygen/Target.cc

@@ -368,7 +368,7 @@ void PackageTarget::DoGenerate() const
 
 		for ( size_t i = 0; i < it->second.size(); ++i )
 			{
-			fprintf(file.f, ":doc:`/scripts/%s`\n",
+			fprintf(file.f, ":doc:`/scripts/%s`\n\n",
 			        it->second[i]->Name().c_str());
 
 			vector<string> cmnts = it->second[i]->GetComments();

src/broxygen/utils.cc

@@ -63,7 +63,7 @@ bool broxygen::prettify_params(string& s)
 			if ( identifier == "Returns" )
 				subst = ":returns";
 			else
-				subst = ":param " + identifier;
+				subst = ":" + identifier;
 
 			s.replace(identifier_start_pos, identifier.size(), subst);
 			return true;
@@ -127,3 +127,9 @@ bool broxygen::is_all_whitespace(const string& s)
 
 	return true;
 	}
+
+string broxygen::redef_indication(const string& from_script)
+	{
+	return fmt("(present if :doc:`/scripts/%s` is loaded)",
+	           from_script.c_str());
+	}

src/broxygen/utils.h

@@ -13,7 +13,7 @@ namespace broxygen {
  * Transform content of a Broxygen comment which may contain function
  * parameter or return value documentation to a prettier reST format.
  * @param s Content from a Broxygen comment to transform. "id: ..." and
- * "Returns: ..." change to ":param id: ..." and ":returns: ...".
+ * "Returns: ..." change to ":id: ..." and ":returns: ...".
  * @return Whether any content in \a s was transformed.
  */
 bool prettify_params(std::string& s);
@@ -56,6 +56,12 @@ size_t end_of_first_sentence(const std::string& s);
  */
 bool is_all_whitespace(const std::string& s);
 
+/**
+ * @return a string indicating the script that has redef'd an enum value or
+ * record field.
+ */
+std::string redef_indication(const std::string& from_script);
+
 } // namespace broxygen
 
 #endif

src/main.cc

@@ -123,8 +123,6 @@ vector<string> params;
 char* proc_status_file = 0;
 int snaplen = 0;	// this gets set from the scripting-layer's value
 
-TypeAliasMap type_aliases;
-
 OpaqueType* md5_type = 0;
 OpaqueType* sha1_type = 0;
 OpaqueType* sha256_type = 0;

src/parse.y

@@ -179,7 +179,7 @@ static attr_list* copy_attr_list(attr_list* al)
 
 static void extend_record(ID* id, type_decl_list* fields, attr_list* attrs)
 	{
-	set<BroType*> types = type_aliases[id->Name()];
+	set<BroType*> types = BroType::GetAliases(id->Name());
 
 	if ( types.empty() )
 		{

testing/btest/Baseline/doc.broxygen.example/example.rst

@@ -223,7 +223,7 @@ Events
    link.  Use the see role instead: :bro:see:`BroxygenExample::a_function`.
    
 
-   :param name: Describe the argument here.
+   :name: Describe the argument here.
 
 Functions
 #########
@@ -237,11 +237,11 @@ Functions
    empty comments is optional, but improves readability of script.
    
 
-   :param tag: Function arguments can be described
+   :tag: Function arguments can be described
         like this.
    
 
-   :param msg: Another param.
+   :msg: Another param.
    
 
    :returns: Describe the return type here.

testing/btest/Baseline/doc.broxygen.func-params/autogen-reST-func-params.rst

@@ -5,9 +5,9 @@
    This is a global function declaration.
    
 
-   :param i: First param.
+   :i: First param.
 
-   :param j: Second param.
+   :j: Second param.
    
 
    :returns: A string.
@@ -20,9 +20,9 @@
          This is a record field function.
          
 
-         :param i: First param.
+         :i: First param.
 
-         :param j: Second param.
+         :j: Second param.
          
 
          :returns: A string.

testing/btest/Baseline/doc.broxygen.identifier/test.rst

@@ -191,11 +191,11 @@
    empty comments is optional, but improves readability of script.
    
 
-   :param tag: Function arguments can be described
+   :tag: Function arguments can be described
         like this.
    
 
-   :param msg: Another param.
+   :msg: Another param.
    
 
    :returns: Describe the return type here.
@@ -212,7 +212,7 @@
    link.  Use the see role instead: :bro:see:`BroxygenExample::a_function`.
    
 
-   :param name: Describe the argument here.
+   :name: Describe the argument here.
 
 .. bro:id:: BroxygenExample::function_without_proto
 

testing/btest/Baseline/doc.broxygen.package/test.rst

@@ -10,7 +10,9 @@ extra scripts needed or used by the documentation process.
 
 :doc:`/scripts/broxygen/__load__.bro`
 
+
 :doc:`/scripts/broxygen/example.bro`
+
    This is an example script that demonstrates Broxygen-style
    documentation.  It generally will make most sense when viewing
    the script's raw source code and comparing to the HTML-rendered