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

Various changes to documentation framework.

Browse source 
- Reorganize top-level 'doc' Makefile target so submodules can easily
  add their own doc-generating routines to it.  e.g. the Bro project
  makes a placeholder 'doc' target, then adds 'restdoc', 'sphinxdoc';
  later Broccoli can add it's own target as a dependency for generating
  API docs.

- Fixed generated docs for BIFs not being organized under a base/
  subdirectory like the original source files.

- Fixed documentation style for function parameters not applying to
  functions declared as record fields.

- Misc. script documentation tweaks to address warnings given by Sphinx.
This commit is contained in:
Jon Siwek 2011-09-07 10:02:15 -05:00
parent eda2245e9e
commit 80e154ba3c
13 changed files with 137 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

38
src/scan.l
View file

@ -80,6 +80,19 @@ static const char* canon_doc_comment(const char* comment)
return ( comment[0] == ' ' ) ? comment + 1 : comment;
}
static std::string canon_doc_func_param(const char* id_start)
{
std::string id_name(id_start, strcspn(id_start, ":"));
const char* comment = id_start + id_name.size() + 1;
std::string doc;
if ( id_name == "Returns" )
doc.append(":returns:").append(comment);
else
doc.append(":param ").append(id_name).append(":").append(comment);
return doc;
}
static ino_t get_inode_num(FILE* f, const char* filename)
{
struct stat b;
@ -155,6 +168,12 @@ ESCSEQ (\\([^\n]|[0-7]+|x[[:xdigit:]]+))
return TOK_POST_DOC;
}
<DOC>##{OWS}{ID}:.* {
const char* id_start = skip_whitespace(yytext + 2);
yylval.str = copy_string(canon_doc_func_param(id_start).c_str());
return TOK_DOC;
}
<DOC>##.* {
if ( yytext[2] != '#' )
{
@ -169,20 +188,6 @@ ESCSEQ (\\([^\n]|[0-7]+|x[[:xdigit:]]+))
// Comment is documenting either a function parameter or return type,
// so appropriate reST markup substitutions are automatically made
// in order to distinguish them from other comments.
const char* id_start = skip_whitespace(yytext + 2);
size_t id_len = strcspn(id_start, ":");
char* id_name = new char[id_len + 1];
strncpy(id_name, id_start, id_len);
id_name[id_len] = '\0';
const char* comment = id_start + id_len + 1;
std::string doc;
if ( streq(id_name, "Returns") )
doc.append(":returns:").append(comment);
else
doc.append(":param ").append(id_name).append(":").append(comment);
if ( ! reST_doc_comments )
reST_doc_comments = new std::list<std::string>();
@ -192,9 +197,8 @@ ESCSEQ (\\([^\n]|[0-7]+|x[[:xdigit:]]+))
// 2) has a blank line between it and non-field-list reST markup,
// which is required for correct HTML rendering by Sphinx
reST_doc_comments->push_back("");
reST_doc_comments->push_back(doc);
delete [] id_name;
const char* id_start = skip_whitespace(yytext + 2);
reST_doc_comments->push_back(canon_doc_func_param(id_start));
}
}