Various changes to documentation framework.

- Reorganize top-level 'doc' Makefile target so submodules can easily
  add their own doc-generating routines to it.  e.g. the Bro project
  makes a placeholder 'doc' target, then adds 'restdoc', 'sphinxdoc';
  later Broccoli can add it's own target as a dependency for generating
  API docs.

- Fixed generated docs for BIFs not being organized under a base/
  subdirectory like the original source files.

- Fixed documentation style for function parameters not applying to
  functions declared as record fields.

- Misc. script documentation tweaks to address warnings given by Sphinx.

src/CMakeLists.txt

@@ -418,6 +418,7 @@ collect_headers(bro_HEADERS ${bro_SRCS})
 
 add_definitions(-DBRO_SCRIPT_INSTALL_PATH="${BRO_SCRIPT_INSTALL_PATH}")
 add_definitions(-DBRO_SCRIPT_SOURCE_PATH="${BRO_SCRIPT_SOURCE_PATH}")
+add_definitions(-DBRO_BUILD_PATH="${CMAKE_CURRENT_BINARY_DIR}")
 
 add_executable(bro ${bro_SRCS} ${bro_HEADERS})
 

src/scan.l

@@ -80,6 +80,19 @@ static const char* canon_doc_comment(const char* comment)
 	return ( comment[0] == ' ' ) ? comment + 1 : comment;
 	}
 
+static std::string canon_doc_func_param(const char* id_start)
+	{
+	std::string id_name(id_start, strcspn(id_start, ":"));
+	const char* comment = id_start + id_name.size() + 1;
+	std::string doc;
+
+	if ( id_name == "Returns" )
+		doc.append(":returns:").append(comment);
+	else
+		doc.append(":param ").append(id_name).append(":").append(comment);
+	return doc;
+	}
+
 static ino_t get_inode_num(FILE* f, const char* filename)
 	{
 	struct stat b;
@@ -155,6 +168,12 @@ ESCSEQ	(\\([^\n]|[0-7]+|x[[:xdigit:]]+))
 	return TOK_POST_DOC;
 }
 
+<DOC>##{OWS}{ID}:.* {
+	const char* id_start = skip_whitespace(yytext + 2);
+	yylval.str = copy_string(canon_doc_func_param(id_start).c_str());
+	return TOK_DOC;
+}
+
 <DOC>##.* {
 	if ( yytext[2] != '#' )
 		{
@@ -169,20 +188,6 @@ ESCSEQ	(\\([^\n]|[0-7]+|x[[:xdigit:]]+))
 		// Comment is documenting either a function parameter or return type,
 		// so appropriate reST markup substitutions are automatically made
 		// in order to distinguish them from other comments.
-		const char* id_start = skip_whitespace(yytext + 2);
-		size_t id_len = strcspn(id_start, ":");
-		char* id_name = new char[id_len + 1];
-		strncpy(id_name, id_start, id_len);
-		id_name[id_len] = '\0';
-		const char* comment = id_start + id_len + 1;
-
-		std::string doc;
-
-		if ( streq(id_name, "Returns") )
-			doc.append(":returns:").append(comment);
-		else
-			doc.append(":param ").append(id_name).append(":").append(comment);
-
 		if ( ! reST_doc_comments )
 			reST_doc_comments = new std::list<std::string>();
 
@@ -192,9 +197,8 @@ ESCSEQ	(\\([^\n]|[0-7]+|x[[:xdigit:]]+))
 		// 2) has a blank line between it and non-field-list reST markup,
 		//    which is required for correct HTML rendering by Sphinx
 		reST_doc_comments->push_back("");
-		reST_doc_comments->push_back(doc);
-
-		delete [] id_name;
+		const char* id_start = skip_whitespace(yytext + 2);
+		reST_doc_comments->push_back(canon_doc_func_param(id_start));
 		}
 }
 

src/util.cc

@@ -891,7 +891,7 @@ const char* normalize_path(const char* path)
 	return copy_string(new_path.c_str());
 	}
 
-// Returns the subpath of the root Bro script install/source directory in
+// Returns the subpath of the root Bro script install/source/build directory in
 // which the loaded file is located.  If it's not under a subpath of that
 // directory (e.g. cwd or custom path) then the full path is returned.
 void get_script_subpath(const std::string& full_filename, const char** subpath)
@@ -909,11 +909,15 @@ void get_script_subpath(const std::string& full_filename, const char** subpath)
 
 	// first check if this is some subpath of the installed scripts root path,
 	// if not check if it's a subpath of the script source root path,
-	// if neither, will just use the given directory
+	// then check if it's a subpath of the build directory (where BIF scripts
+	// will get generated).
+	// If none of those, will just use the given directory.
 	if ( (p=my_subpath.find(BRO_SCRIPT_INSTALL_PATH)) != std::string::npos )
 		my_subpath.erase(0, strlen(BRO_SCRIPT_INSTALL_PATH));
 	else if ( (p=my_subpath.find(BRO_SCRIPT_SOURCE_PATH)) != std::string::npos )
 		my_subpath.erase(0, strlen(BRO_SCRIPT_SOURCE_PATH));
+	else if ( (p=my_subpath.find(BRO_BUILD_PATH)) != std::string::npos )
+		my_subpath.erase(0, strlen(BRO_BUILD_PATH));
 
 	// if root path found, remove path separators until next path component
 	if ( p != std::string::npos )