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

Revise autodoc tracking of public vs private script interfaces

Browse source 
A bro script's public interface is taken to mean any identifier declared
in the global scope that optionally is exported from some namespace/module.
Or more simply: ID::IsGlobal()
This commit is contained in:
Jon Siwek 2011-03-24 12:32:32 -05:00
parent c2f0332b5f
commit 2e88c5100c
4 changed files with 20 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

13
src/BroDoc.cc
View file

@ -152,6 +152,7 @@ void BroDoc::WriteDocFile() const
WriteBroDocObjList(redefs, true, "Redefinitions", '~');
WriteSectionHeading("Private Interface", '-');
WriteBroDocObjList(options, false, "Options", '~');
WriteBroDocObjList(state_vars, false, "State Variables", '~');
WriteBroDocObjList(types, false, "Types", '~');
WriteBroDocObjList(events, false, "Events", '~');
@ -177,7 +178,7 @@ void BroDoc::WriteStringList(const char* format,
}
void BroDoc::WriteBroDocObjList(const std::list<const BroDocObj*>& l,
bool exportCond,
bool wantPublic,
const char* heading,
char underline) const
{
@ -185,18 +186,12 @@ void BroDoc::WriteBroDocObjList(const std::list<const BroDocObj*>& l,
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 ( wantPublic )
if ( (*it)->IsPublicAPI() )
(*it)->WriteReST(reST_file);
}
else
{
// write out only those that have comments and are not exported
if ( !(*it)->IsPublicAPI() && (*it)->HasDocumentation() )
if ( ! (*it)->IsPublicAPI() )
(*it)->WriteReST(reST_file);
}
}
}

8
src/BroDoc.h
View file

@ -198,15 +198,15 @@ protected:
/**
* 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 wantPublic If true, filter out objects that are not declared
* in the global scope. If false, filter out those that are in
* the global scope.
* @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,
bool wantPublic,
const char* heading,
char underline) const;

8
src/BroDocObj.h
View file

@ -37,11 +37,13 @@ public:
void WriteReST(FILE* file) const;
/**
* Check whether this documentation is part of the public API
* (The declaration was while in an export section).
* Check whether this documentation is part of the public API. In
* other words, this means that the identifier is declared as part of
* the global scope (has GLOBAL namespace or is exported from another
* namespace).
* @return true if the ID was declared in an export section, else false
*/
bool IsPublicAPI() const { return broID->IsExport(); }
bool IsPublicAPI() const { return broID->IsGlobal(); }
/**
* Return whether this object has documentation (## comments)

15
src/parse.y
View file

@ -157,13 +157,12 @@ static void add_enum_comment (std::list<std::string>* comments)
cur_enum_type_doc->AddComment(current_module, cur_enum_elem_id, comments);
}
static ID* create_dummy_id (const char* name, BroType* type)
static ID* create_dummy_id (const ID* id, BroType* type)
{
// normally, install_ID() figures out the right IDScope
// but it doesn't matter for the dummy ID so use SCOPE_GLOBAL
ID* fake_id = new ID(copy_string(name), SCOPE_GLOBAL, is_export);
ID* fake_id = new ID(copy_string(id->Name()), (IDScope) id->Scope(),
is_export);
fake_id->SetType(type);
type->SetTypeID(copy_string(name));
type->SetTypeID(copy_string(id->Name()));
fake_id->MakeType();
return fake_id;
}
@ -1009,7 +1008,7 @@ decl:
do_doc_token_stop();
if ( generate_documentation )
{
ID* fake_id = create_dummy_id($3->Name(), cur_enum_type_doc);
ID* fake_id = create_dummy_id($3, cur_enum_type_doc);
cur_enum_type_doc = 0;
BroDocObj* o = new BroDocObj(fake_id, reST_doc_comments, true);
o->SetRole(true);
@ -1028,7 +1027,7 @@ decl:
TypeTag t = $2->AsType()->Tag();
if ( t == TYPE_ENUM && cur_enum_type_doc )
{
ID* fake = create_dummy_id($2->Name(), cur_enum_type_doc);
ID* fake = create_dummy_id($2, cur_enum_type_doc);
cur_enum_type_doc = 0;
current_reST_doc->AddType(
new BroDocObj(fake, reST_doc_comments, true));
@ -1036,7 +1035,7 @@ decl:
else if ( t == TYPE_RECORD && fake_type_decl_list )
{
BroType* fake_record = new RecordType(fake_type_decl_list);
ID* fake = create_dummy_id($2->Name(), fake_record);
ID* fake = create_dummy_id($2, fake_record);
fake_type_decl_list = 0;
current_reST_doc->AddType(
new BroDocObj(fake, reST_doc_comments, true));