Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-04 07:38:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Revising BroDoc*.h internal/api documentation.

Browse source
This commit is contained in:
Jon Siwek 2011-03-15 15:38:43 -05:00
parent f67c0892e5
commit dbf2b9996e
2 changed files with 57 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

57
src/BroDoc.h
View file

@ -90,14 +90,63 @@ public:
*/
void SetAuthor(const std::string& s) { author_name = s; }
//TODO: document these better
// the rest of these need to be called from the parser
/**
* 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 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 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 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); }
/**
@ -126,8 +175,8 @@ protected:
std::list<std::string> imports;
std::list<std::string> port_analysis;
std::list<const BroDocObj*> options; // identifiers with &redef attr
std::list<const BroDocObj*> state_vars; // identifiers without &redef?
std::list<const BroDocObj*> options;
std::list<const BroDocObj*> state_vars;
std::list<const BroDocObj*> types;
const BroDocObj* notices;
std::list<const BroDocObj*> events;

17
src/BroDocObj.h
View file

@ -27,20 +27,11 @@ public:
~BroDocObj();
/**
* writes the reST representation of this object which includes
* 1) any of the "##" comments (stored internally in reST_doc_string)
* To make things easy, I think we should assume that the documenter
* writes their comments such that anything after ## is valid reST
* so that at parse time the ## is just stripped and the remainder
* is scheduled to be inserted as-is into the reST.
* TODO: prepare for some kind of filtering mechanism that transforms
* the reST as written into new reST before being written out.
* This allows for additional custom markup or macros when writing
* pure reST might be inconvenient.
* 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
* Could be implemented similar to the ID::DescribeExtended(ODesc)
* expect with new directives/roles that we'll later teach to Sphinx
* via a "bro domain".
* @param The (already opened) file to write the reST to.
*/
void WriteReST(FILE* file) const;