diff --git a/src/Attr.cc b/src/Attr.cc index f7f7f0576a..6e6f6c4ca6 100644 --- a/src/Attr.cc +++ b/src/Attr.cc @@ -59,9 +59,14 @@ void Attr::DescribeReST(ODesc* d) const d->SP(); d->Add("="); d->SP(); - d->Add("``"); - expr->Describe(d); - d-> Add("``"); + if ( expr->Type()->Tag() == TYPE_FUNC ) + d->Add(":bro:type:`func`"); + else + { + d->Add("``"); + expr->Describe(d); + d-> Add("``"); + } } } diff --git a/src/BroDoc.cc b/src/BroDoc.cc index d0815abe4a..23ed3ee189 100644 --- a/src/BroDoc.cc +++ b/src/BroDoc.cc @@ -48,6 +48,7 @@ BroDoc::~BroDoc() if ( fclose( reST_file ) ) fprintf(stderr, "Failed to close %s", reST_filename.c_str()); FreeBroDocObjPtrList(options); + FreeBroDocObjPtrList(constants); FreeBroDocObjPtrList(state_vars); FreeBroDocObjPtrList(types); FreeBroDocObjPtrList(notices); @@ -146,21 +147,21 @@ void BroDoc::WriteDocFile() const 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", '~'); + WriteInterface("Public Interface", '-', '~', true); + WriteInterface("Private Interface", '-', '~', false); + } - WriteSectionHeading("Private Interface", '-'); - WriteBroDocObjList(options, false, "Options", '~'); - WriteBroDocObjList(state_vars, false, "State Variables", '~'); - WriteBroDocObjList(types, false, "Types", '~'); - WriteBroDocObjList(events, false, "Events", '~'); - WriteBroDocObjList(functions, false, "Functions", '~'); - WriteBroDocObjList(redefs, false, "Redefinitions", '~'); +void BroDoc::WriteInterface(const char* heading, char underline, + char sub, bool isPublic) const + { + WriteSectionHeading(heading, underline); + WriteBroDocObjList(options, isPublic, "Options", sub); + WriteBroDocObjList(constants, isPublic, "Constants", sub); + WriteBroDocObjList(state_vars, isPublic, "State Variables", sub); + WriteBroDocObjList(types, isPublic, "Types", sub); + WriteBroDocObjList(events, isPublic, "Events", sub); + WriteBroDocObjList(functions, isPublic, "Functions", sub); + WriteBroDocObjList(redefs, isPublic, "Redefinitions", sub); } void BroDoc::WriteStringList(const char* format, diff --git a/src/BroDoc.h b/src/BroDoc.h index 04d8206eaa..b1969d0da9 100644 --- a/src/BroDoc.h +++ b/src/BroDoc.h @@ -35,10 +35,7 @@ public: * 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. + * the export section). */ virtual void WriteDocFile() const; @@ -93,6 +90,16 @@ public: */ void AddOption(const BroDocObj* o) { options.push_back(o); } + /** + * Schedules documentation of a script constant. An option is + * defined as any variable in the script that is declared 'const' + * and does *not* have the '&redef' attribute. + * @param o A pointer to a BroDocObj which contains the internal + * Bro language representation of the script constant and + * also any associated comments about it. + */ + void AddConstant(const BroDocObj* o) { constants.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' @@ -167,6 +174,7 @@ protected: std::list port_analysis; std::list options; + std::list constants; std::list state_vars; std::list types; std::list notices; @@ -235,6 +243,19 @@ protected: * within the reST document */ void WriteSectionHeading(const char* heading, char underline) const; + + /** + * Writes out the reST for either the script's public or private interface + * @param heading The title of the interfaces section heading + * @param underline The underline character to use for the interface + * section + * @param subunderline The underline character to use for interface + * sub-sections + * @param isPublic Whether to write out the public or private script + * interface + */ + void WriteInterface(const char* heading, char underline, char subunderline, + bool isPublic) const; private: /** diff --git a/src/ID.cc b/src/ID.cc index c4cf5a58c1..b3fcf8f5c3 100644 --- a/src/ID.cc +++ b/src/ID.cc @@ -651,12 +651,26 @@ void ID::DescribeReST(ODesc* d, bool is_role) const } if ( val && type && - type->InternalType() != TYPE_INTERNAL_OTHER && + type->Tag() != TYPE_FUNC && type->InternalType() != TYPE_INTERNAL_VOID ) { - d->Add(":Init: "); - val->DescribeReST(d); - d->NL(); + if ( type->InternalType() == TYPE_INTERNAL_OTHER ) + { + d->Add(":Init:"); + d->NL(); + d->NL(); + d->Add("::"); + d->NL(); + d->PushIndent(); + val->DescribeReST(d); + d->PopIndent(); + } + else + { + d->Add(":Init: "); + val->DescribeReST(d); + d->NL(); + } } } diff --git a/src/Val.cc b/src/Val.cc index 05ca0adc65..012ca92773 100644 --- a/src/Val.cc +++ b/src/Val.cc @@ -576,9 +576,14 @@ void Val::Describe(ODesc* d) const void Val::DescribeReST(ODesc* d) const { - d->Add("``"); - ValDescribeReST(d); - d->Add("``"); + if ( type->InternalType() == TYPE_INTERNAL_OTHER ) + Describe(d); + else + { + d->Add("``"); + ValDescribeReST(d); + d->Add("``"); + } } void Val::ValDescribe(ODesc* d) const diff --git a/src/parse.y b/src/parse.y index d561fa8e06..1e32bcdbef 100644 --- a/src/parse.y +++ b/src/parse.y @@ -991,6 +991,9 @@ decl: if ( $2->FindAttr(ATTR_REDEF) ) current_reST_doc->AddOption( new BroDocObj($2, reST_doc_comments)); + else + current_reST_doc->AddConstant( + new BroDocObj($2, reST_doc_comments)); } | TOK_REDEF global_id opt_type init_class opt_init opt_attr ';'