Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-02 22:58:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Tabifying BroDoc* sources to make consistent with general style.

Browse source
This commit is contained in:
Jon Siwek 2011-03-15 16:48:51 -05:00
parent dbf2b9996e
commit 9e13d15f29
4 changed files with 399 additions and 399 deletions
Download patch file Download diff file Expand all files Collapse all files

272
src/BroDoc.cc
View file

@ -7,179 +7,179 @@
#include "BroDocObj.h" #include "BroDocObj.h"
BroDoc::BroDoc(const std::string& sourcename) BroDoc::BroDoc(const std::string& sourcename)
{ {
#ifdef DEBUG #ifdef DEBUG
fprintf(stdout, "Documenting source: %s\n", sourcename.c_str()); fprintf(stdout, "Documenting source: %s\n", sourcename.c_str());
#endif #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('.'); size_t ext_pos = source_filename.find_last_of('.');
std::string ext = source_filename.substr(ext_pos + 1); std::string ext = source_filename.substr(ext_pos + 1);
if ( ext_pos == std::string::npos || ext != "bro" ) if ( ext_pos == std::string::npos || ext != "bro" )
{ {
if ( source_filename != "bro.init" ) if ( source_filename != "bro.init" )
{ {
fprintf(stderr, fprintf(stderr,
"Warning: documenting file without .bro extension: %s\n", "Warning: documenting file without .bro extension: %s\n",
sourcename.c_str()); sourcename.c_str());
} }
else else
{ {
// Force the reST documentation file to be "bro.init.rst" // Force the reST documentation file to be "bro.init.rst"
ext_pos = std::string::npos; ext_pos = std::string::npos;
} }
} }
reST_filename = source_filename.substr(0, ext_pos); reST_filename = source_filename.substr(0, ext_pos);
reST_filename += ".rst"; reST_filename += ".rst";
reST_file = fopen(reST_filename.c_str(), "w"); reST_file = fopen(reST_filename.c_str(), "w");
if ( ! reST_file ) if ( ! reST_file )
fprintf(stderr, "Failed to open %s", reST_filename.c_str()); fprintf(stderr, "Failed to open %s", reST_filename.c_str());
#ifdef DEBUG #ifdef DEBUG
else else
fprintf(stdout, "Created reST document: %s\n", reST_filename.c_str()); fprintf(stdout, "Created reST document: %s\n", reST_filename.c_str());
#endif #endif
notices = 0; notices = 0;
} }
BroDoc::~BroDoc() BroDoc::~BroDoc()
{ {
if ( reST_file ) if ( reST_file )
if ( fclose( reST_file ) ) if ( fclose( reST_file ) )
fprintf(stderr, "Failed to close %s", reST_filename.c_str()); fprintf(stderr, "Failed to close %s", reST_filename.c_str());
FreeBroDocObjPtrList(options); FreeBroDocObjPtrList(options);
FreeBroDocObjPtrList(state_vars); FreeBroDocObjPtrList(state_vars);
FreeBroDocObjPtrList(types); FreeBroDocObjPtrList(types);
FreeBroDocObjPtrList(events); FreeBroDocObjPtrList(events);
FreeBroDocObjPtrList(functions); FreeBroDocObjPtrList(functions);
FreeBroDocObjPtrList(redefs); FreeBroDocObjPtrList(redefs);
if ( notices ) delete notices; if ( notices ) delete notices;
} }
void BroDoc::SetPacketFilter(const std::string& s) void BroDoc::SetPacketFilter(const std::string& s)
{ {
packet_filter = s; packet_filter = s;
size_t pos1 = s.find("{\n"); size_t pos1 = s.find("{\n");
size_t pos2 = s.find("}"); size_t pos2 = s.find("}");
if ( pos1 != std::string::npos && pos2 != std::string::npos ) if ( pos1 != std::string::npos && pos2 != std::string::npos )
packet_filter = s.substr(pos1 + 2, pos2 - 2); packet_filter = s.substr(pos1 + 2, pos2 - 2);
} }
void BroDoc::AddPortAnalysis(const std::string& analyzer, void BroDoc::AddPortAnalysis(const std::string& analyzer,
const std::string& ports) const std::string& ports)
{ {
std::string reST_string = analyzer + "::\n" + ports + "\n"; std::string reST_string = analyzer + "::\n" + ports + "\n";
port_analysis.push_back(reST_string); port_analysis.push_back(reST_string);
} }
void BroDoc::WriteDocFile() const void BroDoc::WriteDocFile() const
{ {
WriteToDoc("%s\n", source_filename.c_str()); WriteToDoc("%s\n", source_filename.c_str());
for ( size_t i = 0; i < source_filename.length(); ++i ) for ( size_t i = 0; i < source_filename.length(); ++i )
WriteToDoc("="); WriteToDoc("=");
WriteToDoc("\n\n"); WriteToDoc("\n\n");
WriteSectionHeading("Summary", '-'); WriteSectionHeading("Summary", '-');
WriteStringList("%s\n", "%s\n\n", 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: "); WriteToDoc(":Namespaces: ");
WriteStringList("`%s`, ", "`%s`\n", modules); WriteStringList("`%s`, ", "`%s`\n", modules);
WriteToDoc(":Imports:\n"); WriteToDoc(":Imports:\n");
WriteStringList(" :bro:script: `%s`\n", WriteStringList("\t:bro:script: `%s`\n",
" :bro:script: `%s`\n\n", imports); "\t:bro:script: `%s`\n\n", imports);
WriteSectionHeading("Notices", '-'); WriteSectionHeading("Notices", '-');
if ( notices ) if ( notices )
notices->WriteReST(reST_file); notices->WriteReST(reST_file);
WriteSectionHeading("Port Analysis", '-'); WriteSectionHeading("Port Analysis", '-');
WriteStringList("%s", port_analysis); WriteStringList("%s", port_analysis);
WriteSectionHeading("Packet Filter", '-'); WriteSectionHeading("Packet Filter", '-');
WriteToDoc("%s\n", packet_filter.c_str()); WriteToDoc("%s\n", packet_filter.c_str());
WriteSectionHeading("Public Interface", '-'); WriteSectionHeading("Public Interface", '-');
WriteBroDocObjList(options, true, "Options", '~'); WriteBroDocObjList(options, true, "Options", '~');
WriteBroDocObjList(state_vars, true, "State Variables", '~'); WriteBroDocObjList(state_vars, true, "State Variables", '~');
WriteBroDocObjList(types, true, "Types", '~'); WriteBroDocObjList(types, true, "Types", '~');
WriteBroDocObjList(events, true, "Events", '~'); WriteBroDocObjList(events, true, "Events", '~');
WriteBroDocObjList(functions, true, "Functions", '~'); WriteBroDocObjList(functions, true, "Functions", '~');
WriteBroDocObjList(redefs, true, "Redefinitions", '~'); WriteBroDocObjList(redefs, true, "Redefinitions", '~');
WriteSectionHeading("Private Interface", '-'); WriteSectionHeading("Private Interface", '-');
WriteBroDocObjList(state_vars, false, "State Variables", '~'); WriteBroDocObjList(state_vars, false, "State Variables", '~');
WriteBroDocObjList(types, false, "Types", '~'); WriteBroDocObjList(types, false, "Types", '~');
WriteBroDocObjList(events, false, "Events", '~'); WriteBroDocObjList(events, false, "Events", '~');
WriteBroDocObjList(functions, false, "Functions", '~'); WriteBroDocObjList(functions, false, "Functions", '~');
WriteBroDocObjList(redefs, false, "Redefinitions", '~'); WriteBroDocObjList(redefs, false, "Redefinitions", '~');
} }
void BroDoc::WriteStringList(const char* format, void BroDoc::WriteStringList(const char* format,
const char* last_format, const char* last_format,
const std::list<std::string>& l) const const std::list<std::string>& l) const
{ {
if ( l.empty() ) if ( l.empty() )
{ {
WriteToDoc("\n"); WriteToDoc("\n");
return; return;
} }
std::list<std::string>::const_iterator it; std::list<std::string>::const_iterator it;
std::list<std::string>::const_iterator last = l.end(); std::list<std::string>::const_iterator last = l.end();
last--; last--;
for ( it = l.begin(); it != last; ++it ) for ( it = l.begin(); it != last; ++it )
WriteToDoc(format, it->c_str()); WriteToDoc(format, it->c_str());
WriteToDoc(last_format, last->c_str()); WriteToDoc(last_format, last->c_str());
} }
void BroDoc::WriteBroDocObjList(const std::list<const BroDocObj*>& l, void BroDoc::WriteBroDocObjList(const std::list<const BroDocObj*>& l,
bool exportCond, bool exportCond,
const char* heading, const char* heading,
char underline) const char underline) const
{ {
WriteSectionHeading(heading, underline); WriteSectionHeading(heading, underline);
std::list<const BroDocObj*>::const_iterator it; std::list<const BroDocObj*>::const_iterator it;
for ( it = l.begin(); it != l.end(); ++it ) for ( it = l.begin(); it != l.end(); ++it )
{ {
if ( exportCond ) if ( exportCond )
{ {
// write out only those in an export section // write out only those in an export section
if ( (*it)->IsPublicAPI() ) if ( (*it)->IsPublicAPI() )
(*it)->WriteReST(reST_file); (*it)->WriteReST(reST_file);
} }
else else
{ {
// write out only those that have comments and are not exported // write out only those that have comments and are not exported
if ( !(*it)->IsPublicAPI() && (*it)->HasDocumentation() ) if ( !(*it)->IsPublicAPI() && (*it)->HasDocumentation() )
(*it)->WriteReST(reST_file); (*it)->WriteReST(reST_file);
} }
} }
} }
void BroDoc::WriteToDoc(const char* format, ...) const void BroDoc::WriteToDoc(const char* format, ...) const
{ {
va_list argp; va_list argp;
va_start(argp, format); va_start(argp, format);
vfprintf(reST_file, format, argp); vfprintf(reST_file, format, argp);
va_end(argp); va_end(argp);
} }
void BroDoc::WriteSectionHeading(const char* heading, char underline) const void BroDoc::WriteSectionHeading(const char* heading, char underline) const
{ {
WriteToDoc("%s\n", heading); WriteToDoc("%s\n", heading);
size_t len = strlen(heading); size_t len = strlen(heading);
for ( size_t i = 0; i < len; ++i ) for ( size_t i = 0; i < len; ++i )
WriteToDoc("%c", underline); WriteToDoc("%c", underline);
WriteToDoc("\n"); WriteToDoc("\n");
} }
void BroDoc::FreeBroDocObjPtrList(std::list<const BroDocObj*>& l) void BroDoc::FreeBroDocObjPtrList(std::list<const BroDocObj*>& l)
{ {
std::list<const BroDocObj*>::iterator it; std::list<const BroDocObj*>::iterator it;
for ( it = l.begin(); it != l.end(); ++it ) for ( it = l.begin(); it != l.end(); ++it )
delete *it; delete *it;
l.clear(); l.clear();
} }

398
src/BroDoc.h
View file

@ -10,236 +10,236 @@
class BroDoc { class BroDoc {
public: public:
/** /**
* BroDoc constructor * BroDoc constructor
* Given a Bro script, opens new file in the current working directory * Given a Bro script, opens new file in the current working directory
* that will contain reST documentation generated from the parsing * that will contain reST documentation generated from the parsing
* of the Bro script. The new reST file will be named similar to * of the Bro script. The new reST file will be named similar to
* the filename of the Bro script that generates it, except any * the filename of the Bro script that generates it, except any
* ".bro" file extension is stripped and ".rst" takes it place. * ".bro" file extension is stripped and ".rst" takes it place.
* If the filename doesn't end in ".bro", then ".rst" is just appended. * 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 * @param sourcename The name of the Bro script for which to generate
* documentation. May contain a path. * documentation. May contain a path.
*/ */
BroDoc(const std::string& sourcename); BroDoc(const std::string& sourcename);
/** /**
* BroDoc destructor * BroDoc destructor
* Closes the file that was opened by the constructor and frees up * Closes the file that was opened by the constructor and frees up
* memory taken by BroDocObj objects. * memory taken by BroDocObj objects.
*/ */
~BroDoc(); ~BroDoc();
/** /**
* Write out full reST documentation for the Bro script that was parsed. * Write out full reST documentation for the Bro script that was parsed.
* BroDoc's default implementation of this function will care * BroDoc's default implementation of this function will care
* about whether declarations made in the Bro script are part of * about whether declarations made in the Bro script are part of
* the public versus private interface (whether things are declared in * the public versus private interface (whether things are declared in
* the export section). Things in a script's export section make it * the export section). Things in a script's export section make it
* into the reST output regardless of whether they have ## comments * into the reST output regardless of whether they have ## comments
* but things outside the export section are only output into the reST * but things outside the export section are only output into the reST
* if they have ## comments. * if they have ## comments.
*/ */
virtual void WriteDocFile() const; virtual void WriteDocFile() const;
/** /**
* Schedules some summarizing text to be output directly into the reST doc. * 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 * This should be called whenever the scanner sees a line in the Bro script
* starting with "##!" * starting with "##!"
* @param s The summary text to add to the reST doc. * @param s The summary text to add to the reST doc.
*/ */
void AddSummary(const std::string& s) { summary.push_back(s); } void AddSummary(const std::string& s) { summary.push_back(s); }
/** /**
* Schedules an import (@load) to be documented. * Schedules an import (@load) to be documented.
* This should be called whenever the scanner sees an @load. * This should be called whenever the scanner sees an @load.
* @param s The name of the imported script. * @param s The name of the imported script.
*/ */
void AddImport(const std::string& s) { imports.push_back(s); } void AddImport(const std::string& s) { imports.push_back(s); }
/** /**
* Schedules a namespace (module) to be documented. * Schedules a namespace (module) to be documented.
* This should be called whenever the parser sees a TOK_MODULE. * This should be called whenever the parser sees a TOK_MODULE.
* @param s The namespace (module) identifier's name. * @param s The namespace (module) identifier's name.
*/ */
void AddModule(const std::string& s) { modules.push_back(s); } void AddModule(const std::string& s) { modules.push_back(s); }
/** /**
* Sets the way the script changes the "capture_filters" table. * Sets the way the script changes the "capture_filters" table.
* This is determined by the scanner checking for changes to * This is determined by the scanner checking for changes to
* the "capture_filters" table after each of Bro's input scripts * the "capture_filters" table after each of Bro's input scripts
* (given as command line arguments to Bro) are finished being parsed. * (given as command line arguments to Bro) are finished being parsed.
* @param s The value "capture_filters" as given by TableVal::Describe() * @param s The value "capture_filters" as given by TableVal::Describe()
*/ */
void SetPacketFilter(const std::string& s); void SetPacketFilter(const std::string& s);
/** /**
* Schedules documentation of a given set of ports being associated * Schedules documentation of a given set of ports being associated
* with a particular analyzer as a result of the current script * with a particular analyzer as a result of the current script
* being loaded -- the way the "dpd_config" table is changed. * being loaded -- the way the "dpd_config" table is changed.
* @param analyzer An analyzer that changed the "dpd_config" table. * @param analyzer An analyzer that changed the "dpd_config" table.
* @param ports The set of ports assigned to the analyzer in table. * @param ports The set of ports assigned to the analyzer in table.
*/ */
void AddPortAnalysis(const std::string& analyzer, const std::string& ports); void AddPortAnalysis(const std::string& analyzer, const std::string& ports);
/** /**
* Sets the author of the script. * Sets the author of the script.
* The scanner should call this when it sees "## Author: ..." * The scanner should call this when it sees "## Author: ..."
* @param s The name, email, etc. of the script author(s). Must be * @param s The name, email, etc. of the script author(s). Must be
* all on one line. * all on one line.
*/ */
void SetAuthor(const std::string& s) { author_name = s; } void SetAuthor(const std::string& s) { author_name = s; }
/** /**
* Schedules documentation of a script option. An option is * Schedules documentation of a script option. An option is
* defined as any variable in the script that is declared 'const' * defined as any variable in the script that is declared 'const'
* and has the '&redef' attribute. * and has the '&redef' attribute.
* @param o A pointer to a BroDocObj which contains the internal * @param o A pointer to a BroDocObj which contains the internal
* Bro language representation of the script option and * Bro language representation of the script option and
* also any associated comments about it. * also any associated comments about it.
*/ */
void AddOption(const BroDocObj* o) { options.push_back(o); } void AddOption(const BroDocObj* o) { options.push_back(o); }
/** /**
* Schedules documentation of a script state variable. A state variable * Schedules documentation of a script state variable. A state variable
* is defined as any variable in the script that is declared 'global' * is defined as any variable in the script that is declared 'global'
* @param o A pointer to a BroDocObj which contains the internal * @param o A pointer to a BroDocObj which contains the internal
* Bro language representation of the script state variable * Bro language representation of the script state variable
* and also any associated comments about it. * and also any associated comments about it.
*/ */
void AddStateVar(const BroDocObj* o) { state_vars.push_back(o); } void AddStateVar(const BroDocObj* o) { state_vars.push_back(o); }
/** /**
* Schedules documentation of a type declared by the script. * Schedules documentation of a type declared by the script.
* @param o A pointer to a BroDocObj which contains the internal * @param o A pointer to a BroDocObj which contains the internal
* Bro language representation of the script option and * Bro language representation of the script option and
* also any associated comments about it. * also any associated comments about it.
*/ */
void AddType(const BroDocObj* o) { types.push_back(o); } void AddType(const BroDocObj* o) { types.push_back(o); }
/** /**
* Schedules documentation of a Notice (enum redef) declared by script * Schedules documentation of a Notice (enum redef) declared by script
* @param o A pointer to a BroDocObj which contains the internal * @param o A pointer to a BroDocObj which contains the internal
* Bro language representation of the Notice and also * Bro language representation of the Notice and also
* any associated comments about it. * any associated comments about it.
*/ */
void AddNotice(const BroDocObj* o) { notices = o; } void AddNotice(const BroDocObj* o) { notices = o; }
/** /**
* Schedules documentation of an event declared by the script. * Schedules documentation of an event declared by the script.
* @param o A pointer to a BroDocObj which contains the internal * @param o A pointer to a BroDocObj which contains the internal
* Bro language representation of the script event and * Bro language representation of the script event and
* also any associated comments about it. * also any associated comments about it.
*/ */
void AddEvent(const BroDocObj* o) { events.push_back(o); } void AddEvent(const BroDocObj* o) { events.push_back(o); }
/** /**
* Schedules documentation of a function declared by the script. * Schedules documentation of a function declared by the script.
* @param o A pointer to a BroDocObj which contains the internal * @param o A pointer to a BroDocObj which contains the internal
* Bro language representation of the script function and * Bro language representation of the script function and
* also any associated comments about it. * also any associated comments about it.
*/ */
void AddFunction(const BroDocObj* o) { functions.push_back(o); } void AddFunction(const BroDocObj* o) { functions.push_back(o); }
/** /**
* Schedules documentation of a redef done by the script * Schedules documentation of a redef done by the script
* @param o A pointer to a BroDocObj which contains the internal * @param o A pointer to a BroDocObj which contains the internal
* Bro language representation of the script identifier * Bro language representation of the script identifier
* that was redefined and also any associated comments. * that was redefined and also any associated comments.
*/ */
void AddRedef(const BroDocObj* o) { redefs.push_back(o); } void AddRedef(const BroDocObj* o) { redefs.push_back(o); }
/** /**
* Gets the name of the Bro script source file for which reST * Gets the name of the Bro script source file for which reST
* documentation is being generated. * documentation is being generated.
* @return A char* to the start of the source file's name. * @return A char* to the start of the source file's name.
*/ */
const char* GetSourceFileName() const { return source_filename.c_str(); } const char* GetSourceFileName() const { return source_filename.c_str(); }
/** /**
* Gets the name of the generated reST documentation file. * Gets the name of the generated reST documentation file.
* @return A char* to the start of the generated reST file's name. * @return A char* to the start of the generated reST file's name.
*/ */
const char* GetOutputFileName() const { return reST_filename.c_str(); } const char* GetOutputFileName() const { return reST_filename.c_str(); }
protected: protected:
FILE* reST_file; FILE* reST_file;
std::string reST_filename; std::string reST_filename;
std::string source_filename; std::string source_filename;
std::string author_name; std::string author_name;
std::string packet_filter; std::string packet_filter;
std::list<std::string> ls; std::list<std::string> ls;
std::list<std::string> modules; std::list<std::string> modules;
std::list<std::string> summary; std::list<std::string> summary;
std::list<std::string> imports; std::list<std::string> imports;
std::list<std::string> port_analysis; std::list<std::string> port_analysis;
std::list<const BroDocObj*> options; std::list<const BroDocObj*> options;
std::list<const BroDocObj*> state_vars; std::list<const BroDocObj*> state_vars;
std::list<const BroDocObj*> types; std::list<const BroDocObj*> types;
const BroDocObj* notices; const BroDocObj* notices;
std::list<const BroDocObj*> events; std::list<const BroDocObj*> events;
std::list<const BroDocObj*> functions; std::list<const BroDocObj*> functions;
std::list<const BroDocObj*> redefs; 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. * If the list is empty, prints a newline character.
* @param format A printf style format string for elements of the list * @param format A printf style format string for elements of the list
* except for the last one in the list * except for the last one in the list
* @param last_format A printf style format string to use for the last * @param last_format A printf style format string to use for the last
* element of the list * element of the list
* @param l A reference to a list of strings * @param l A reference to a list of strings
*/ */
void WriteStringList(const char* format, void WriteStringList(const char* format,
const char* last_format, const char* last_format,
const std::list<std::string>& l) const; const std::list<std::string>& l) const;
/** /**
* @see WriteStringList(const char*, const char*, * @see WriteStringList(const char*, const char*,
const std::list<std::string>&>) * const std::list<std::string>&>)
*/ */
void WriteStringList(const char* format, void WriteStringList(const char* format,
const std::list<std::string>& l) const const std::list<std::string>& l) const
{ WriteStringList(format, format, l); } { WriteStringList(format, format, l); }
/** /**
* Writes out a list of BroDocObj objects to the reST document * Writes out a list of BroDocObj objects to the reST document
* @param l A list of BroDocObj pointers * @param l A list of BroDocObj pointers
* @param exportCond If true, filter out objects that are not in an * @param exportCond If true, filter out objects that are not in an
* export section. If false, filter out those that are in * export section. If false, filter out those that are in
* an export section. * an export section.
* @param heading The title of the section to create in the reST doc. * @param heading The title of the section to create in the reST doc.
* @param underline The character to use to underline the reST * @param underline The character to use to underline the reST
* section heading. * section heading.
*/ */
void WriteBroDocObjList(const std::list<const BroDocObj*>& l, void WriteBroDocObjList(const std::list<const BroDocObj*>& l,
bool exportCond, bool exportCond,
const char* heading, const char* heading,
char underline) const; char underline) const;
/** /**
* A wrapper to fprintf() that always uses the reST document * A wrapper to fprintf() that always uses the reST document
* for the FILE* argument. * for the FILE* argument.
* @param format A printf style format string. * @param format A printf style format string.
*/ */
void WriteToDoc(const char* format, ...) const; void WriteToDoc(const char* format, ...) const;
/** /**
* Writes out a reST section heading * Writes out a reST section heading
* @param heading The title of the heading to create * @param heading The title of the heading to create
* @param underline The character to use to underline the section title * @param underline The character to use to underline the section title
within the reST document * within the reST document
*/ */
void WriteSectionHeading(const char* heading, char underline) const; void WriteSectionHeading(const char* heading, char underline) const;
private: private:
/** /**
* Frees memory allocated to BroDocObj's objects in a given list. * Frees memory allocated to BroDocObj's objects in a given list.
* @param a reference to a list of BroDocObj pointers * @param a reference to a list of BroDocObj pointers
*/ */
void FreeBroDocObjPtrList(std::list<const BroDocObj*>& l); void FreeBroDocObjPtrList(std::list<const BroDocObj*>& l);
}; };
#endif #endif

50
src/BroDocObj.cc
View file

@ -6,34 +6,34 @@
BroDocObj::BroDocObj(const ID* id, std::list<std::string>*& reST, BroDocObj::BroDocObj(const ID* id, std::list<std::string>*& reST,
bool is_fake) bool is_fake)
{ {
broID = id; broID = id;
reST_doc_strings = reST; reST_doc_strings = reST;
reST = 0; reST = 0;
is_fake_id = is_fake; is_fake_id = is_fake;
} }
BroDocObj::~BroDocObj() BroDocObj::~BroDocObj()
{ {
delete reST_doc_strings; delete reST_doc_strings;
if ( is_fake_id ) delete broID; if ( is_fake_id ) delete broID;
} }
void BroDocObj::WriteReST(FILE* file) const void BroDocObj::WriteReST(FILE* file) const
{ {
ODesc desc; ODesc desc;
desc.SetQuotes(1); desc.SetQuotes(1);
broID->DescribeReST(&desc); broID->DescribeReST(&desc);
fprintf(file, "%s\n", desc.Description()); fprintf(file, "%s\n", desc.Description());
if ( HasDocumentation() ) if ( HasDocumentation() )
{ {
fprintf(file, "\t.. bro:comment::\n"); fprintf(file, "\t.. bro:comment::\n");
std::list<std::string>::const_iterator it; std::list<std::string>::const_iterator it;
for ( it = reST_doc_strings->begin(); for ( it = reST_doc_strings->begin();
it != reST_doc_strings->end(); ++it) it != reST_doc_strings->end(); ++it)
fprintf(file, "\t\t%s\n", it->c_str()); fprintf(file, "\t\t%s\n", it->c_str());
} }
fprintf(file, "\n"); fprintf(file, "\n");
} }

78
src/BroDocObj.h
View file

@ -9,51 +9,51 @@
class BroDocObj { class BroDocObj {
public: public:
/** /**
* BroDocObj constructor * BroDocObj constructor
* @param id a pointer to an identifier that is to be documented * @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 * @param reST a reference to a pointer of a list of strings that
represent the reST documentation for the ID. The pointer * represent the reST documentation for the ID. The pointer
will be set to 0 after this constructor finishes. * will be set to 0 after this constructor finishes.
* @param is_fake whether the ID* is a dummy just for doc purposes * @param is_fake whether the ID* is a dummy just for doc purposes
*/ */
BroDocObj(const ID* id, std::list<std::string>*& reST, BroDocObj(const ID* id, std::list<std::string>*& reST,
bool is_fake = false); bool is_fake = false);
/** /**
* BroDocObj destructor * BroDocObj destructor
* Deallocates the memory associated with the list of reST strings * Deallocates the memory associated with the list of reST strings
*/ */
~BroDocObj(); ~BroDocObj();
/** /**
* Writes the reST representation of this object which includes * Writes the reST representation of this object which includes
* 1) Any "##" or "##<" stylized comments. * 1) Any "##" or "##<" stylized comments.
* Anything after these style of comments is inserted as-is into * Anything after these style of comments is inserted as-is into
* the reST document. * the reST document.
* 2) a reST friendly description of the ID * 2) a reST friendly description of the ID
* @param The (already opened) file to write the reST to. * @param The (already opened) file to write the reST to.
*/ */
void WriteReST(FILE* file) const; void WriteReST(FILE* file) const;
/** /**
* Check whether this documentation is part of the public API * Check whether this documentation is part of the public API
* (The declaration was while in an export section). * (The declaration was while in an export section).
* @return true if the ID was declared in an export section, else false * @return true if the ID was declared in an export section, else false
*/ */
bool IsPublicAPI() const { return broID->IsExport(); } bool IsPublicAPI() const { return broID->IsExport(); }
/** /**
* Return whether this object has documentation (## comments) * Return whether this object has documentation (## comments)
* @return true if the ID has comments associated with it * @return true if the ID has comments associated with it
*/ */
bool HasDocumentation() const { return reST_doc_strings && bool HasDocumentation() const { return reST_doc_strings &&
reST_doc_strings->size() > 0; } reST_doc_strings->size() > 0; }
protected: protected:
std::list<std::string>* reST_doc_strings; std::list<std::string>* reST_doc_strings;
const ID* broID; const ID* broID;
bool is_fake_id; /**< Whether the ID* is a dummy just for doc purposes */ bool is_fake_id; /**< Whether the ID* is a dummy just for doc purposes */
private: private:
}; };