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

Allow Broxygen markup "##<" for more general use.

Browse source
This commit is contained in:
Jon Siwek 2011-12-16 11:21:49 -06:00
parent 0b8b14a0ed
commit 3b91df8cf5
5 changed files with 32 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

10
doc/scripts/example.bro
View file

@ -1,5 +1,5 @@
##! This is an example script that demonstrates how to document. Comments
##! of the form ``##!`` are for the script summary. The contents of
##! This is an example script that demonstrates documentation features.
##! Comments of the form ``##!`` are for the script summary. The contents of
##! these comments are transferred directly into the auto-generated
##! `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
##! (reST) document's summary section.
@ -22,8 +22,8 @@
# field comments, it's necessary to disambiguate the field with
# which a comment associates: e.g. "##<" can be used on the same line
# as a field to signify the comment relates to it and not the
# following field. "##<" is not meant for general use, just
# record/enum fields.
# following field. "##<" can also be used more generally in any
# variable declarations to associate with the last-declared identifier.
#
# Generally, the auto-doc comments (##) are associated with the
# next declaration/identifier found in the script, but the doc framework
@ -151,7 +151,7 @@ export {
const an_option: set[addr, addr, string] &redef;
# default initialization will be self-documenting
const option_with_init = 0.01 secs &redef;
const option_with_init = 0.01 secs &redef; ##< More docs can be added here.
############## state variables ############
# right now, I'm defining this as any global

3
src/BroDocObj.cc
View file

@ -4,9 +4,12 @@
#include "ID.h"
#include "BroDocObj.h"
BroDocObj* BroDocObj::last = 0;
BroDocObj::BroDocObj(const ID* id, std::list<std::string>*& reST,
bool is_fake)
{
last = this;
broID = id;
reST_doc_strings = reST;
reST = 0;

14
src/BroDocObj.h
View file

@ -103,6 +103,20 @@ public:
*/
int LongestShortDescLen() const;
/**
* Adds a reST documentation string to this BroDocObj's list.
* @param s the documentation string to append.
*/
void AddDocString(const std::string& s)
{
if ( ! reST_doc_strings )
reST_doc_strings = new std::list<std::string>();
reST_doc_strings->push_back(s);
FormulateShortDesc();
}
static BroDocObj* last;
protected:
std::list<std::string>* reST_doc_strings;
std::list<std::string> short_desc;

5
src/scan.l
View file

@ -201,6 +201,11 @@ ESCSEQ (\\([^\n]|[0-7]+|x[[:xdigit:]]+))
}
}
##<.* {
if ( generate_documentation && BroDocObj::last )
BroDocObj::last->AddDocString(canon_doc_comment(yytext + 3));
}
##.* {
if ( generate_documentation && (yytext[2] != '#') )
{

8
testing/btest/Baseline/doc.autogen-reST-example/example.rst
View file

@ -7,8 +7,8 @@ example.bro
Overview
--------
This is an example script that demonstrates how to document. Comments
of the form ``##!`` are for the script summary. The contents of
This is an example script that demonstrates documentation features.
Comments of the form ``##!`` are for the script summary. The contents of
these comments are transferred directly into the auto-generated
`reStructuredText <http://docutils.sourceforge.net/rst.html>`_
(reST) document's summary section.
@ -34,7 +34,7 @@ Options
============================================================================ ======================================
:bro:id:`Example::an_option`: :bro:type:`set` :bro:attr:`&redef` add documentation for "an_option" here
:bro:id:`Example::option_with_init`: :bro:type:`interval` :bro:attr:`&redef`
:bro:id:`Example::option_with_init`: :bro:type:`interval` :bro:attr:`&redef` More docs can be added here.
============================================================================ ======================================
State Variables
@ -128,6 +128,8 @@ Options
:Attributes: :bro:attr:`&redef`
:Default: ``10.0 msecs``
More docs can be added here.
State Variables
~~~~~~~~~~~~~~~
.. bro:id:: Example::a_var