mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 14:48:21 +00:00
Tabifying BroDoc* sources to make consistent with general style.
This commit is contained in:
Jon Siwek
parent
dbf2b9996e
commit
9e13d15f29
4 changed files with 399 additions and 399 deletions
272
src/BroDoc.cc
272
src/BroDoc.cc
|
|
@ -7,179 +7,179 @@
|
|||
#include "BroDocObj.h"
|
||||
|
||||
BroDoc::BroDoc(const std::string& sourcename)
|
||||
{
|
||||
{
|
||||
#ifdef DEBUG
|
||||
fprintf(stdout, "Documenting source: %s\n", sourcename.c_str());
|
||||
fprintf(stdout, "Documenting source: %s\n", sourcename.c_str());
|
||||
#endif
|
||||
source_filename = sourcename.substr(sourcename.find_last_of('/') + 1);
|
||||
source_filename = sourcename.substr(sourcename.find_last_of('/') + 1);
|
||||
|
||||
size_t ext_pos = source_filename.find_last_of('.');
|
||||
std::string ext = source_filename.substr(ext_pos + 1);
|
||||
if ( ext_pos == std::string::npos || ext != "bro" )
|
||||
{
|
||||
if ( source_filename != "bro.init" )
|
||||
{
|
||||
fprintf(stderr,
|
||||
"Warning: documenting file without .bro extension: %s\n",
|
||||
sourcename.c_str());
|
||||
}
|
||||
else
|
||||
{
|
||||
// Force the reST documentation file to be "bro.init.rst"
|
||||
ext_pos = std::string::npos;
|
||||
}
|
||||
}
|
||||
size_t ext_pos = source_filename.find_last_of('.');
|
||||
std::string ext = source_filename.substr(ext_pos + 1);
|
||||
if ( ext_pos == std::string::npos || ext != "bro" )
|
||||
{
|
||||
if ( source_filename != "bro.init" )
|
||||
{
|
||||
fprintf(stderr,
|
||||
"Warning: documenting file without .bro extension: %s\n",
|
||||
sourcename.c_str());
|
||||
}
|
||||
else
|
||||
{
|
||||
// Force the reST documentation file to be "bro.init.rst"
|
||||
ext_pos = std::string::npos;
|
||||
}
|
||||
}
|
||||
|
||||
reST_filename = source_filename.substr(0, ext_pos);
|
||||
reST_filename += ".rst";
|
||||
reST_file = fopen(reST_filename.c_str(), "w");
|
||||
reST_filename = source_filename.substr(0, ext_pos);
|
||||
reST_filename += ".rst";
|
||||
reST_file = fopen(reST_filename.c_str(), "w");
|
||||
|
||||
if ( ! reST_file )
|
||||
fprintf(stderr, "Failed to open %s", reST_filename.c_str());
|
||||
if ( ! reST_file )
|
||||
fprintf(stderr, "Failed to open %s", reST_filename.c_str());
|
||||
#ifdef DEBUG
|
||||
else
|
||||
fprintf(stdout, "Created reST document: %s\n", reST_filename.c_str());
|
||||
else
|
||||
fprintf(stdout, "Created reST document: %s\n", reST_filename.c_str());
|
||||
#endif
|
||||
notices = 0;
|
||||
}
|
||||
notices = 0;
|
||||
}
|
||||
|
||||
BroDoc::~BroDoc()
|
||||
{
|
||||
if ( reST_file )
|
||||
if ( fclose( reST_file ) )
|
||||
fprintf(stderr, "Failed to close %s", reST_filename.c_str());
|
||||
FreeBroDocObjPtrList(options);
|
||||
FreeBroDocObjPtrList(state_vars);
|
||||
FreeBroDocObjPtrList(types);
|
||||
FreeBroDocObjPtrList(events);
|
||||
FreeBroDocObjPtrList(functions);
|
||||
FreeBroDocObjPtrList(redefs);
|
||||
if ( notices ) delete notices;
|
||||
}
|
||||
{
|
||||
if ( reST_file )
|
||||
if ( fclose( reST_file ) )
|
||||
fprintf(stderr, "Failed to close %s", reST_filename.c_str());
|
||||
FreeBroDocObjPtrList(options);
|
||||
FreeBroDocObjPtrList(state_vars);
|
||||
FreeBroDocObjPtrList(types);
|
||||
FreeBroDocObjPtrList(events);
|
||||
FreeBroDocObjPtrList(functions);
|
||||
FreeBroDocObjPtrList(redefs);
|
||||
if ( notices ) delete notices;
|
||||
}
|
||||
|
||||
void BroDoc::SetPacketFilter(const std::string& s)
|
||||
{
|
||||
packet_filter = s;
|
||||
size_t pos1 = s.find("{\n");
|
||||
size_t pos2 = s.find("}");
|
||||
if ( pos1 != std::string::npos && pos2 != std::string::npos )
|
||||
packet_filter = s.substr(pos1 + 2, pos2 - 2);
|
||||
}
|
||||
{
|
||||
packet_filter = s;
|
||||
size_t pos1 = s.find("{\n");
|
||||
size_t pos2 = s.find("}");
|
||||
if ( pos1 != std::string::npos && pos2 != std::string::npos )
|
||||
packet_filter = s.substr(pos1 + 2, pos2 - 2);
|
||||
}
|
||||
|
||||
void BroDoc::AddPortAnalysis(const std::string& analyzer,
|
||||
const std::string& ports)
|
||||
{
|
||||
std::string reST_string = analyzer + "::\n" + ports + "\n";
|
||||
port_analysis.push_back(reST_string);
|
||||
}
|
||||
{
|
||||
std::string reST_string = analyzer + "::\n" + ports + "\n";
|
||||
port_analysis.push_back(reST_string);
|
||||
}
|
||||
|
||||
void BroDoc::WriteDocFile() const
|
||||
{
|
||||
WriteToDoc("%s\n", source_filename.c_str());
|
||||
for ( size_t i = 0; i < source_filename.length(); ++i )
|
||||
WriteToDoc("=");
|
||||
WriteToDoc("\n\n");
|
||||
{
|
||||
WriteToDoc("%s\n", source_filename.c_str());
|
||||
for ( size_t i = 0; i < source_filename.length(); ++i )
|
||||
WriteToDoc("=");
|
||||
WriteToDoc("\n\n");
|
||||
|
||||
WriteSectionHeading("Summary", '-');
|
||||
WriteStringList("%s\n", "%s\n\n", summary);
|
||||
WriteSectionHeading("Summary", '-');
|
||||
WriteStringList("%s\n", "%s\n\n", summary);
|
||||
|
||||
WriteToDoc(":Author: %s\n", author_name.c_str());
|
||||
WriteToDoc(":Author: %s\n", author_name.c_str());
|
||||
|
||||
WriteToDoc(":Namespaces: ");
|
||||
WriteStringList("`%s`, ", "`%s`\n", modules);
|
||||
WriteToDoc(":Namespaces: ");
|
||||
WriteStringList("`%s`, ", "`%s`\n", modules);
|
||||
|
||||
WriteToDoc(":Imports:\n");
|
||||
WriteStringList(" :bro:script: `%s`\n",
|
||||
" :bro:script: `%s`\n\n", imports);
|
||||
WriteToDoc(":Imports:\n");
|
||||
WriteStringList("\t:bro:script: `%s`\n",
|
||||
"\t:bro:script: `%s`\n\n", imports);
|
||||
|
||||
WriteSectionHeading("Notices", '-');
|
||||
if ( notices )
|
||||
notices->WriteReST(reST_file);
|
||||
WriteSectionHeading("Notices", '-');
|
||||
if ( notices )
|
||||
notices->WriteReST(reST_file);
|
||||
|
||||
WriteSectionHeading("Port Analysis", '-');
|
||||
WriteStringList("%s", port_analysis);
|
||||
WriteSectionHeading("Port Analysis", '-');
|
||||
WriteStringList("%s", port_analysis);
|
||||
|
||||
WriteSectionHeading("Packet Filter", '-');
|
||||
WriteToDoc("%s\n", packet_filter.c_str());
|
||||
WriteSectionHeading("Packet Filter", '-');
|
||||
WriteToDoc("%s\n", packet_filter.c_str());
|
||||
|
||||
WriteSectionHeading("Public Interface", '-');
|
||||
WriteBroDocObjList(options, true, "Options", '~');
|
||||
WriteBroDocObjList(state_vars, true, "State Variables", '~');
|
||||
WriteBroDocObjList(types, true, "Types", '~');
|
||||
WriteBroDocObjList(events, true, "Events", '~');
|
||||
WriteBroDocObjList(functions, true, "Functions", '~');
|
||||
WriteBroDocObjList(redefs, true, "Redefinitions", '~');
|
||||
WriteSectionHeading("Public Interface", '-');
|
||||
WriteBroDocObjList(options, true, "Options", '~');
|
||||
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", '-');
|
||||
WriteBroDocObjList(state_vars, false, "State Variables", '~');
|
||||
WriteBroDocObjList(types, false, "Types", '~');
|
||||
WriteBroDocObjList(events, false, "Events", '~');
|
||||
WriteBroDocObjList(functions, false, "Functions", '~');
|
||||
WriteBroDocObjList(redefs, false, "Redefinitions", '~');
|
||||
}
|
||||
WriteSectionHeading("Private Interface", '-');
|
||||
WriteBroDocObjList(state_vars, false, "State Variables", '~');
|
||||
WriteBroDocObjList(types, false, "Types", '~');
|
||||
WriteBroDocObjList(events, false, "Events", '~');
|
||||
WriteBroDocObjList(functions, false, "Functions", '~');
|
||||
WriteBroDocObjList(redefs, false, "Redefinitions", '~');
|
||||
}
|
||||
|
||||
void BroDoc::WriteStringList(const char* format,
|
||||
const char* last_format,
|
||||
const std::list<std::string>& l) const
|
||||
{
|
||||
if ( l.empty() )
|
||||
{
|
||||
WriteToDoc("\n");
|
||||
return;
|
||||
}
|
||||
std::list<std::string>::const_iterator it;
|
||||
std::list<std::string>::const_iterator last = l.end();
|
||||
last--;
|
||||
for ( it = l.begin(); it != last; ++it )
|
||||
WriteToDoc(format, it->c_str());
|
||||
WriteToDoc(last_format, last->c_str());
|
||||
}
|
||||
{
|
||||
if ( l.empty() )
|
||||
{
|
||||
WriteToDoc("\n");
|
||||
return;
|
||||
}
|
||||
std::list<std::string>::const_iterator it;
|
||||
std::list<std::string>::const_iterator last = l.end();
|
||||
last--;
|
||||
for ( it = l.begin(); it != last; ++it )
|
||||
WriteToDoc(format, it->c_str());
|
||||
WriteToDoc(last_format, last->c_str());
|
||||
}
|
||||
|
||||
void BroDoc::WriteBroDocObjList(const std::list<const BroDocObj*>& l,
|
||||
bool exportCond,
|
||||
const char* heading,
|
||||
char underline) const
|
||||
{
|
||||
WriteSectionHeading(heading, underline);
|
||||
std::list<const BroDocObj*>::const_iterator it;
|
||||
for ( it = l.begin(); it != l.end(); ++it )
|
||||
{
|
||||
if ( exportCond )
|
||||
{
|
||||
// write out only those in an export section
|
||||
if ( (*it)->IsPublicAPI() )
|
||||
(*it)->WriteReST(reST_file);
|
||||
}
|
||||
else
|
||||
{
|
||||
// write out only those that have comments and are not exported
|
||||
if ( !(*it)->IsPublicAPI() && (*it)->HasDocumentation() )
|
||||
(*it)->WriteReST(reST_file);
|
||||
}
|
||||
}
|
||||
}
|
||||
{
|
||||
WriteSectionHeading(heading, underline);
|
||||
std::list<const BroDocObj*>::const_iterator it;
|
||||
for ( it = l.begin(); it != l.end(); ++it )
|
||||
{
|
||||
if ( exportCond )
|
||||
{
|
||||
// write out only those in an export section
|
||||
if ( (*it)->IsPublicAPI() )
|
||||
(*it)->WriteReST(reST_file);
|
||||
}
|
||||
else
|
||||
{
|
||||
// write out only those that have comments and are not exported
|
||||
if ( !(*it)->IsPublicAPI() && (*it)->HasDocumentation() )
|
||||
(*it)->WriteReST(reST_file);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
void BroDoc::WriteToDoc(const char* format, ...) const
|
||||
{
|
||||
va_list argp;
|
||||
va_start(argp, format);
|
||||
vfprintf(reST_file, format, argp);
|
||||
va_end(argp);
|
||||
}
|
||||
{
|
||||
va_list argp;
|
||||
va_start(argp, format);
|
||||
vfprintf(reST_file, format, argp);
|
||||
va_end(argp);
|
||||
}
|
||||
|
||||
void BroDoc::WriteSectionHeading(const char* heading, char underline) const
|
||||
{
|
||||
WriteToDoc("%s\n", heading);
|
||||
size_t len = strlen(heading);
|
||||
for ( size_t i = 0; i < len; ++i )
|
||||
WriteToDoc("%c", underline);
|
||||
WriteToDoc("\n");
|
||||
}
|
||||
{
|
||||
WriteToDoc("%s\n", heading);
|
||||
size_t len = strlen(heading);
|
||||
for ( size_t i = 0; i < len; ++i )
|
||||
WriteToDoc("%c", underline);
|
||||
WriteToDoc("\n");
|
||||
}
|
||||
|
||||
void BroDoc::FreeBroDocObjPtrList(std::list<const BroDocObj*>& l)
|
||||
{
|
||||
std::list<const BroDocObj*>::iterator it;
|
||||
for ( it = l.begin(); it != l.end(); ++it )
|
||||
delete *it;
|
||||
l.clear();
|
||||
}
|
||||
{
|
||||
std::list<const BroDocObj*>::iterator it;
|
||||
for ( it = l.begin(); it != l.end(); ++it )
|
||||
delete *it;
|
||||
l.clear();
|
||||
}
|
||||
|
|
|
|||
398
src/BroDoc.h
398
src/BroDoc.h
|
|
@ -10,236 +10,236 @@
|
|||
|
||||
class BroDoc {
|
||||
public:
|
||||
/**
|
||||
* BroDoc constructor
|
||||
* Given a Bro script, opens new file in the current working directory
|
||||
* that will contain reST documentation generated from the parsing
|
||||
* of the Bro script. The new reST file will be named similar to
|
||||
* the filename of the Bro script that generates it, except any
|
||||
* ".bro" file extension is stripped and ".rst" takes it place.
|
||||
* If the filename doesn't end in ".bro", then ".rst" is just appended.
|
||||
* @param sourcename The name of the Bro script for which to generate
|
||||
* documentation. May contain a path.
|
||||
*/
|
||||
BroDoc(const std::string& sourcename);
|
||||
/**
|
||||
* BroDoc constructor
|
||||
* Given a Bro script, opens new file in the current working directory
|
||||
* that will contain reST documentation generated from the parsing
|
||||
* of the Bro script. The new reST file will be named similar to
|
||||
* the filename of the Bro script that generates it, except any
|
||||
* ".bro" file extension is stripped and ".rst" takes it place.
|
||||
* If the filename doesn't end in ".bro", then ".rst" is just appended.
|
||||
* @param sourcename The name of the Bro script for which to generate
|
||||
* documentation. May contain a path.
|
||||
*/
|
||||
BroDoc(const std::string& sourcename);
|
||||
|
||||
/**
|
||||
* BroDoc destructor
|
||||
* Closes the file that was opened by the constructor and frees up
|
||||
* memory taken by BroDocObj objects.
|
||||
*/
|
||||
~BroDoc();
|
||||
/**
|
||||
* BroDoc destructor
|
||||
* Closes the file that was opened by the constructor and frees up
|
||||
* memory taken by BroDocObj objects.
|
||||
*/
|
||||
~BroDoc();
|
||||
|
||||
/**
|
||||
* Write out full reST documentation for the Bro script that was parsed.
|
||||
* 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
|
||||
* 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;
|
||||
/**
|
||||
* Write out full reST documentation for the Bro script that was parsed.
|
||||
* 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
|
||||
* 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;
|
||||
|
||||
/**
|
||||
* Schedules some summarizing text to be output directly into the reST doc.
|
||||
* This should be called whenever the scanner sees a line in the Bro script
|
||||
* starting with "##!"
|
||||
* @param s The summary text to add to the reST doc.
|
||||
*/
|
||||
void AddSummary(const std::string& s) { summary.push_back(s); }
|
||||
/**
|
||||
* Schedules some summarizing text to be output directly into the reST doc.
|
||||
* This should be called whenever the scanner sees a line in the Bro script
|
||||
* starting with "##!"
|
||||
* @param s The summary text to add to the reST doc.
|
||||
*/
|
||||
void AddSummary(const std::string& s) { summary.push_back(s); }
|
||||
|
||||
/**
|
||||
* Schedules an import (@load) to be documented.
|
||||
* This should be called whenever the scanner sees an @load.
|
||||
* @param s The name of the imported script.
|
||||
*/
|
||||
void AddImport(const std::string& s) { imports.push_back(s); }
|
||||
/**
|
||||
* Schedules an import (@load) to be documented.
|
||||
* This should be called whenever the scanner sees an @load.
|
||||
* @param s The name of the imported script.
|
||||
*/
|
||||
void AddImport(const std::string& s) { imports.push_back(s); }
|
||||
|
||||
/**
|
||||
* Schedules a namespace (module) to be documented.
|
||||
* This should be called whenever the parser sees a TOK_MODULE.
|
||||
* @param s The namespace (module) identifier's name.
|
||||
*/
|
||||
void AddModule(const std::string& s) { modules.push_back(s); }
|
||||
/**
|
||||
* Schedules a namespace (module) to be documented.
|
||||
* This should be called whenever the parser sees a TOK_MODULE.
|
||||
* @param s The namespace (module) identifier's name.
|
||||
*/
|
||||
void AddModule(const std::string& s) { modules.push_back(s); }
|
||||
|
||||
/**
|
||||
* Sets the way the script changes the "capture_filters" table.
|
||||
* This is determined by the scanner checking for changes to
|
||||
* the "capture_filters" table after each of Bro's input scripts
|
||||
* (given as command line arguments to Bro) are finished being parsed.
|
||||
* @param s The value "capture_filters" as given by TableVal::Describe()
|
||||
*/
|
||||
void SetPacketFilter(const std::string& s);
|
||||
/**
|
||||
* Sets the way the script changes the "capture_filters" table.
|
||||
* This is determined by the scanner checking for changes to
|
||||
* the "capture_filters" table after each of Bro's input scripts
|
||||
* (given as command line arguments to Bro) are finished being parsed.
|
||||
* @param s The value "capture_filters" as given by TableVal::Describe()
|
||||
*/
|
||||
void SetPacketFilter(const std::string& s);
|
||||
|
||||
/**
|
||||
* Schedules documentation of a given set of ports being associated
|
||||
* with a particular analyzer as a result of the current script
|
||||
* being loaded -- the way the "dpd_config" table is changed.
|
||||
* @param analyzer An analyzer that changed the "dpd_config" table.
|
||||
* @param ports The set of ports assigned to the analyzer in table.
|
||||
*/
|
||||
void AddPortAnalysis(const std::string& analyzer, const std::string& ports);
|
||||
/**
|
||||
* Schedules documentation of a given set of ports being associated
|
||||
* with a particular analyzer as a result of the current script
|
||||
* being loaded -- the way the "dpd_config" table is changed.
|
||||
* @param analyzer An analyzer that changed the "dpd_config" table.
|
||||
* @param ports The set of ports assigned to the analyzer in table.
|
||||
*/
|
||||
void AddPortAnalysis(const std::string& analyzer, const std::string& ports);
|
||||
|
||||
/**
|
||||
* Sets the author of the script.
|
||||
* The scanner should call this when it sees "## Author: ..."
|
||||
* @param s The name, email, etc. of the script author(s). Must be
|
||||
* all on one line.
|
||||
*/
|
||||
void SetAuthor(const std::string& s) { author_name = s; }
|
||||
/**
|
||||
* Sets the author of the script.
|
||||
* The scanner should call this when it sees "## Author: ..."
|
||||
* @param s The name, email, etc. of the script author(s). Must be
|
||||
* all on one line.
|
||||
*/
|
||||
void SetAuthor(const std::string& s) { author_name = s; }
|
||||
|
||||
/**
|
||||
* Schedules documentation of a script option. An option is
|
||||
* defined as any variable in the script that is declared 'const'
|
||||
* and has the '&redef' attribute.
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script option and
|
||||
* also any associated comments about it.
|
||||
*/
|
||||
void AddOption(const BroDocObj* o) { options.push_back(o); }
|
||||
/**
|
||||
* Schedules documentation of a script option. An option is
|
||||
* defined as any variable in the script that is declared 'const'
|
||||
* and has the '&redef' attribute.
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script option and
|
||||
* also any associated comments about it.
|
||||
*/
|
||||
void AddOption(const BroDocObj* o) { options.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'
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script state variable
|
||||
* and also any associated comments about it.
|
||||
*/
|
||||
void AddStateVar(const BroDocObj* o) { state_vars.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'
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script state variable
|
||||
* and also any associated comments about it.
|
||||
*/
|
||||
void AddStateVar(const BroDocObj* o) { state_vars.push_back(o); }
|
||||
|
||||
/**
|
||||
* Schedules documentation of a type declared by the script.
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script option and
|
||||
* also any associated comments about it.
|
||||
*/
|
||||
void AddType(const BroDocObj* o) { types.push_back(o); }
|
||||
/**
|
||||
* Schedules documentation of a type declared by the script.
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script option and
|
||||
* also any associated comments about it.
|
||||
*/
|
||||
void AddType(const BroDocObj* o) { types.push_back(o); }
|
||||
|
||||
/**
|
||||
* Schedules documentation of a Notice (enum redef) declared by script
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the Notice and also
|
||||
* any associated comments about it.
|
||||
*/
|
||||
void AddNotice(const BroDocObj* o) { notices = o; }
|
||||
/**
|
||||
* Schedules documentation of a Notice (enum redef) declared by script
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the Notice and also
|
||||
* any associated comments about it.
|
||||
*/
|
||||
void AddNotice(const BroDocObj* o) { notices = o; }
|
||||
|
||||
/**
|
||||
* Schedules documentation of an event declared by the script.
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script event and
|
||||
* also any associated comments about it.
|
||||
*/
|
||||
void AddEvent(const BroDocObj* o) { events.push_back(o); }
|
||||
/**
|
||||
* Schedules documentation of an event declared by the script.
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script event and
|
||||
* also any associated comments about it.
|
||||
*/
|
||||
void AddEvent(const BroDocObj* o) { events.push_back(o); }
|
||||
|
||||
/**
|
||||
* Schedules documentation of a function declared by the script.
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script function and
|
||||
* also any associated comments about it.
|
||||
*/
|
||||
void AddFunction(const BroDocObj* o) { functions.push_back(o); }
|
||||
* Schedules documentation of a function declared by the script.
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script function and
|
||||
* also any associated comments about it.
|
||||
*/
|
||||
void AddFunction(const BroDocObj* o) { functions.push_back(o); }
|
||||
|
||||
/**
|
||||
* Schedules documentation of a redef done by the script
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script identifier
|
||||
* that was redefined and also any associated comments.
|
||||
*/
|
||||
void AddRedef(const BroDocObj* o) { redefs.push_back(o); }
|
||||
* Schedules documentation of a redef done by the script
|
||||
* @param o A pointer to a BroDocObj which contains the internal
|
||||
* Bro language representation of the script identifier
|
||||
* that was redefined and also any associated comments.
|
||||
*/
|
||||
void AddRedef(const BroDocObj* o) { redefs.push_back(o); }
|
||||
|
||||
/**
|
||||
* Gets the name of the Bro script source file for which reST
|
||||
* documentation is being generated.
|
||||
* @return A char* to the start of the source file's name.
|
||||
*/
|
||||
const char* GetSourceFileName() const { return source_filename.c_str(); }
|
||||
/**
|
||||
* Gets the name of the Bro script source file for which reST
|
||||
* documentation is being generated.
|
||||
* @return A char* to the start of the source file's name.
|
||||
*/
|
||||
const char* GetSourceFileName() const { return source_filename.c_str(); }
|
||||
|
||||
/**
|
||||
* Gets the name of the generated reST documentation file.
|
||||
* @return A char* to the start of the generated reST file's name.
|
||||
*/
|
||||
const char* GetOutputFileName() const { return reST_filename.c_str(); }
|
||||
/**
|
||||
* Gets the name of the generated reST documentation file.
|
||||
* @return A char* to the start of the generated reST file's name.
|
||||
*/
|
||||
const char* GetOutputFileName() const { return reST_filename.c_str(); }
|
||||
|
||||
protected:
|
||||
FILE* reST_file;
|
||||
std::string reST_filename;
|
||||
std::string source_filename;
|
||||
std::string author_name;
|
||||
std::string packet_filter;
|
||||
FILE* reST_file;
|
||||
std::string reST_filename;
|
||||
std::string source_filename;
|
||||
std::string author_name;
|
||||
std::string packet_filter;
|
||||
|
||||
std::list<std::string> ls;
|
||||
std::list<std::string> modules;
|
||||
std::list<std::string> summary;
|
||||
std::list<std::string> imports;
|
||||
std::list<std::string> port_analysis;
|
||||
std::list<std::string> ls;
|
||||
std::list<std::string> modules;
|
||||
std::list<std::string> summary;
|
||||
std::list<std::string> imports;
|
||||
std::list<std::string> port_analysis;
|
||||
|
||||
std::list<const BroDocObj*> options;
|
||||
std::list<const BroDocObj*> state_vars;
|
||||
std::list<const BroDocObj*> types;
|
||||
const BroDocObj* notices;
|
||||
std::list<const BroDocObj*> events;
|
||||
std::list<const BroDocObj*> functions;
|
||||
std::list<const BroDocObj*> redefs;
|
||||
std::list<const BroDocObj*> options;
|
||||
std::list<const BroDocObj*> state_vars;
|
||||
std::list<const BroDocObj*> types;
|
||||
const BroDocObj* notices;
|
||||
std::list<const BroDocObj*> events;
|
||||
std::list<const BroDocObj*> functions;
|
||||
std::list<const BroDocObj*> redefs;
|
||||
|
||||
/**
|
||||
* Writes out a list of strings to the reST document.
|
||||
/**
|
||||
* Writes out a list of strings to the reST document.
|
||||
* If the list is empty, prints a newline character.
|
||||
* @param format A printf style format string for elements of the list
|
||||
* except for the last one in the list
|
||||
* @param last_format A printf style format string to use for the last
|
||||
* element of the list
|
||||
* @param l A reference to a list of strings
|
||||
*/
|
||||
void WriteStringList(const char* format,
|
||||
const char* last_format,
|
||||
const std::list<std::string>& l) const;
|
||||
* @param format A printf style format string for elements of the list
|
||||
* except for the last one in the list
|
||||
* @param last_format A printf style format string to use for the last
|
||||
* element of the list
|
||||
* @param l A reference to a list of strings
|
||||
*/
|
||||
void WriteStringList(const char* format,
|
||||
const char* last_format,
|
||||
const std::list<std::string>& l) const;
|
||||
|
||||
/**
|
||||
* @see WriteStringList(const char*, const char*,
|
||||
const std::list<std::string>&>)
|
||||
*/
|
||||
void WriteStringList(const char* format,
|
||||
const std::list<std::string>& l) const
|
||||
{ WriteStringList(format, format, l); }
|
||||
/**
|
||||
* @see WriteStringList(const char*, const char*,
|
||||
* const std::list<std::string>&>)
|
||||
*/
|
||||
void WriteStringList(const char* format,
|
||||
const std::list<std::string>& l) const
|
||||
{ WriteStringList(format, format, l); }
|
||||
|
||||
/**
|
||||
* Writes out a list of BroDocObj objects to the reST document
|
||||
* @param l A list of BroDocObj pointers
|
||||
* @param exportCond If true, filter out objects that are not in an
|
||||
* export section. If false, filter out those that are in
|
||||
* an export section.
|
||||
* @param heading The title of the section to create in the reST doc.
|
||||
* @param underline The character to use to underline the reST
|
||||
* section heading.
|
||||
*/
|
||||
void WriteBroDocObjList(const std::list<const BroDocObj*>& l,
|
||||
bool exportCond,
|
||||
const char* heading,
|
||||
char underline) const;
|
||||
/**
|
||||
* Writes out a list of BroDocObj objects to the reST document
|
||||
* @param l A list of BroDocObj pointers
|
||||
* @param exportCond If true, filter out objects that are not in an
|
||||
* export section. If false, filter out those that are in
|
||||
* an export section.
|
||||
* @param heading The title of the section to create in the reST doc.
|
||||
* @param underline The character to use to underline the reST
|
||||
* section heading.
|
||||
*/
|
||||
void WriteBroDocObjList(const std::list<const BroDocObj*>& l,
|
||||
bool exportCond,
|
||||
const char* heading,
|
||||
char underline) const;
|
||||
|
||||
/**
|
||||
* A wrapper to fprintf() that always uses the reST document
|
||||
* for the FILE* argument.
|
||||
* @param format A printf style format string.
|
||||
*/
|
||||
void WriteToDoc(const char* format, ...) const;
|
||||
/**
|
||||
* A wrapper to fprintf() that always uses the reST document
|
||||
* for the FILE* argument.
|
||||
* @param format A printf style format string.
|
||||
*/
|
||||
void WriteToDoc(const char* format, ...) const;
|
||||
|
||||
/**
|
||||
* Writes out a reST section heading
|
||||
* @param heading The title of the heading to create
|
||||
* @param underline The character to use to underline the section title
|
||||
within the reST document
|
||||
*/
|
||||
void WriteSectionHeading(const char* heading, char underline) const;
|
||||
/**
|
||||
* Writes out a reST section heading
|
||||
* @param heading The title of the heading to create
|
||||
* @param underline The character to use to underline the section title
|
||||
* within the reST document
|
||||
*/
|
||||
void WriteSectionHeading(const char* heading, char underline) const;
|
||||
private:
|
||||
|
||||
/**
|
||||
* Frees memory allocated to BroDocObj's objects in a given list.
|
||||
* @param a reference to a list of BroDocObj pointers
|
||||
*/
|
||||
void FreeBroDocObjPtrList(std::list<const BroDocObj*>& l);
|
||||
/**
|
||||
* Frees memory allocated to BroDocObj's objects in a given list.
|
||||
* @param a reference to a list of BroDocObj pointers
|
||||
*/
|
||||
void FreeBroDocObjPtrList(std::list<const BroDocObj*>& l);
|
||||
};
|
||||
|
||||
#endif
|
||||
|
|
|
|||
|
|
@ -6,34 +6,34 @@
|
|||
|
||||
BroDocObj::BroDocObj(const ID* id, std::list<std::string>*& reST,
|
||||
bool is_fake)
|
||||
{
|
||||
broID = id;
|
||||
reST_doc_strings = reST;
|
||||
reST = 0;
|
||||
is_fake_id = is_fake;
|
||||
}
|
||||
{
|
||||
broID = id;
|
||||
reST_doc_strings = reST;
|
||||
reST = 0;
|
||||
is_fake_id = is_fake;
|
||||
}
|
||||
|
||||
BroDocObj::~BroDocObj()
|
||||
{
|
||||
delete reST_doc_strings;
|
||||
if ( is_fake_id ) delete broID;
|
||||
}
|
||||
{
|
||||
delete reST_doc_strings;
|
||||
if ( is_fake_id ) delete broID;
|
||||
}
|
||||
|
||||
void BroDocObj::WriteReST(FILE* file) const
|
||||
{
|
||||
ODesc desc;
|
||||
desc.SetQuotes(1);
|
||||
broID->DescribeReST(&desc);
|
||||
fprintf(file, "%s\n", desc.Description());
|
||||
{
|
||||
ODesc desc;
|
||||
desc.SetQuotes(1);
|
||||
broID->DescribeReST(&desc);
|
||||
fprintf(file, "%s\n", desc.Description());
|
||||
|
||||
if ( HasDocumentation() )
|
||||
{
|
||||
fprintf(file, "\t.. bro:comment::\n");
|
||||
std::list<std::string>::const_iterator it;
|
||||
for ( it = reST_doc_strings->begin();
|
||||
it != reST_doc_strings->end(); ++it)
|
||||
fprintf(file, "\t\t%s\n", it->c_str());
|
||||
}
|
||||
if ( HasDocumentation() )
|
||||
{
|
||||
fprintf(file, "\t.. bro:comment::\n");
|
||||
std::list<std::string>::const_iterator it;
|
||||
for ( it = reST_doc_strings->begin();
|
||||
it != reST_doc_strings->end(); ++it)
|
||||
fprintf(file, "\t\t%s\n", it->c_str());
|
||||
}
|
||||
|
||||
fprintf(file, "\n");
|
||||
}
|
||||
fprintf(file, "\n");
|
||||
}
|
||||
|
|
|
|||
|
|
@ -9,51 +9,51 @@
|
|||
|
||||
class BroDocObj {
|
||||
public:
|
||||
/**
|
||||
* BroDocObj constructor
|
||||
* @param id a pointer to an identifier that is to be documented
|
||||
* @param reST a reference to a pointer of a list of strings that
|
||||
represent the reST documentation for the ID. The pointer
|
||||
will be set to 0 after this constructor finishes.
|
||||
* @param is_fake whether the ID* is a dummy just for doc purposes
|
||||
*/
|
||||
BroDocObj(const ID* id, std::list<std::string>*& reST,
|
||||
bool is_fake = false);
|
||||
/**
|
||||
* BroDocObj constructor
|
||||
* @param id a pointer to an identifier that is to be documented
|
||||
* @param reST a reference to a pointer of a list of strings that
|
||||
* represent the reST documentation for the ID. The pointer
|
||||
* will be set to 0 after this constructor finishes.
|
||||
* @param is_fake whether the ID* is a dummy just for doc purposes
|
||||
*/
|
||||
BroDocObj(const ID* id, std::list<std::string>*& reST,
|
||||
bool is_fake = false);
|
||||
|
||||
/**
|
||||
* BroDocObj destructor
|
||||
* Deallocates the memory associated with the list of reST strings
|
||||
*/
|
||||
~BroDocObj();
|
||||
/**
|
||||
* BroDocObj destructor
|
||||
* Deallocates the memory associated with the list of reST strings
|
||||
*/
|
||||
~BroDocObj();
|
||||
|
||||
/**
|
||||
* Writes the reST representation of this object which includes
|
||||
* 1) Any "##" or "##<" stylized comments.
|
||||
* Anything after these style of comments is inserted as-is into
|
||||
* the reST document.
|
||||
* 2) a reST friendly description of the ID
|
||||
* @param The (already opened) file to write the reST to.
|
||||
*/
|
||||
void WriteReST(FILE* file) const;
|
||||
/**
|
||||
* Writes the reST representation of this object which includes
|
||||
* 1) Any "##" or "##<" stylized comments.
|
||||
* Anything after these style of comments is inserted as-is into
|
||||
* the reST document.
|
||||
* 2) a reST friendly description of the ID
|
||||
* @param The (already opened) file to write the reST to.
|
||||
*/
|
||||
void WriteReST(FILE* file) const;
|
||||
|
||||
/**
|
||||
* Check whether this documentation is part of the public API
|
||||
* (The declaration was while in an export section).
|
||||
* @return true if the ID was declared in an export section, else false
|
||||
*/
|
||||
bool IsPublicAPI() const { return broID->IsExport(); }
|
||||
/**
|
||||
* Check whether this documentation is part of the public API
|
||||
* (The declaration was while in an export section).
|
||||
* @return true if the ID was declared in an export section, else false
|
||||
*/
|
||||
bool IsPublicAPI() const { return broID->IsExport(); }
|
||||
|
||||
/**
|
||||
* Return whether this object has documentation (## comments)
|
||||
* @return true if the ID has comments associated with it
|
||||
*/
|
||||
bool HasDocumentation() const { return reST_doc_strings &&
|
||||
reST_doc_strings->size() > 0; }
|
||||
/**
|
||||
* Return whether this object has documentation (## comments)
|
||||
* @return true if the ID has comments associated with it
|
||||
*/
|
||||
bool HasDocumentation() const { return reST_doc_strings &&
|
||||
reST_doc_strings->size() > 0; }
|
||||
|
||||
protected:
|
||||
std::list<std::string>* reST_doc_strings;
|
||||
const ID* broID;
|
||||
bool is_fake_id; /**< Whether the ID* is a dummy just for doc purposes */
|
||||
std::list<std::string>* reST_doc_strings;
|
||||
const ID* broID;
|
||||
bool is_fake_id; /**< Whether the ID* is a dummy just for doc purposes */
|
||||
|
||||
private:
|
||||
};
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue