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

Another revision for autodoc tracking of public vs private interfaces

Browse source 
A script's public API wasn't simply definable as identifiers
for which ID::IsGlobal() is true, e.g. an unexported identifier with
SCOPE_MODULE will still pass that test and (incorrectly) be considered
public API.

Also, generated reST now omits empty interface sections.
This commit is contained in:
Jon Siwek 2011-03-24 14:04:30 -05:00
parent 2e88c5100c
commit 2490878656
4 changed files with 31 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

22
src/BroDoc.cc
View file

@ -112,8 +112,11 @@ void BroDoc::WriteDocFile() const
WriteSectionHeading("Summary", '-'); WriteSectionHeading("Summary", '-');
WriteStringList("%s\n", "%s\n\n", summary); WriteStringList("%s\n", "%s\n\n", summary);
if ( ! imports.empty() )
{
WriteToDoc(":Imports: "); WriteToDoc(":Imports: ");
WriteStringList(":doc:`%s`, ", ":doc:`%s`\n", imports); WriteStringList(":doc:`%s`, ", ":doc:`%s`\n", imports);
}
WriteToDoc("\n"); WriteToDoc("\n");
@ -182,16 +185,23 @@ void BroDoc::WriteBroDocObjList(const std::list<const BroDocObj*>& l,
const char* heading, const char* heading,
char underline) const char underline) const
{ {
WriteSectionHeading(heading, underline); if ( l.empty() ) return;
std::list<const BroDocObj*>::const_iterator it; std::list<const BroDocObj*>::const_iterator it;
for ( it = l.begin(); it != l.end(); ++it ) bool (*f_ptr)(const BroDocObj* o) = 0;
{
if ( wantPublic ) if ( wantPublic )
if ( (*it)->IsPublicAPI() ) f_ptr = IsPublicAPI;
(*it)->WriteReST(reST_file);
else else
if ( ! (*it)->IsPublicAPI() ) f_ptr = IsPrivateAPI;
it = std::find_if(l.begin(), l.end(), f_ptr);
if ( it == l.end() ) return;
WriteSectionHeading(heading, underline);
while ( it != l.end() )
{
(*it)->WriteReST(reST_file); (*it)->WriteReST(reST_file);
it = find_if(++it, l.end(), f_ptr);
} }
} }

3
src/BroDoc.h
View file

@ -242,6 +242,9 @@ private:
* @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);
static bool IsPublicAPI(const BroDocObj* o) { return o->IsPublicAPI(); }
static bool IsPrivateAPI(const BroDocObj* o) { return ! o->IsPublicAPI(); }
}; };
#endif #endif

6
src/BroDocObj.cc
View file

@ -44,3 +44,9 @@ void BroDocObj::WriteReST(FILE* file) const
fprintf(file, "\n"); fprintf(file, "\n");
} }
bool BroDocObj::IsPublicAPI() const
{
return (broID->Scope() == SCOPE_GLOBAL) ||
(broID->Scope() == SCOPE_MODULE && broID->IsExport());
}

4
src/BroDocObj.h
View file

@ -41,9 +41,9 @@ public:
* other words, this means that the identifier is declared as part of * other words, this means that the identifier is declared as part of
* the global scope (has GLOBAL namespace or is exported from another * the global scope (has GLOBAL namespace or is exported from another
* namespace). * namespace).
* @return true if the ID was declared in an export section, else false * @return true if the identifier is part of the script's public API
*/ */
bool IsPublicAPI() const { return broID->IsGlobal(); } bool IsPublicAPI() const;
/** /**
* Return whether this object has documentation (## comments) * Return whether this object has documentation (## comments)