Commit 53a763d4 authored by David Gobbi's avatar David Gobbi
Browse files

Read all doxygen comments from headers.

With this change, all doxygen comments are read from the headers, including
trailing comments (//!<) and comments that do not appear immediately before
the item they apply too (e.g. comments with \class).  Comment groups are not
not handled.
parent 0b77535e
Pipeline #2806 passed with stage
......@@ -1980,9 +1980,7 @@ static int skip_to_next_directive();
static int skip_conditional_block();
static void doxygen_comment();
static void doxygen_trailing();
static void doxygen_cpp_comment();
static void doxygen_cpp_trailing();
static void doxygen_group_start();
static void doxygen_group_end();
static void vtk_comment();
......@@ -2292,7 +2290,7 @@ do_action: /* This label is used only to access EOF actions. */
case 1:
YY_RULE_SETUP
{ doxygen_trailing(); }
{ doxygen_comment(); }
YY_BREAK
case 2:
YY_RULE_SETUP
......@@ -2328,7 +2326,7 @@ YY_RULE_SETUP
case 7:
YY_RULE_SETUP
{ doxygen_cpp_trailing(); }
{ doxygen_cpp_comment(); }
YY_BREAK
case 8:
YY_RULE_SETUP
......@@ -5091,19 +5089,24 @@ int skip_ahead_until(const char *text)
/*
* Called for / + ** and / + *! doxygen comments (handles entire comment)
* Called for doxygen C-style comments
*/
void doxygen_comment()
{
char linetext[256];
int savelineno = yylineno;
int asterisk, isfirstline = 1;
int type = DoxygenComment;
size_t l = 0, i = 0, base = yyleng;
int c1 = 0, c2 = input();
for (l = 0; l < yyleng; l++)
{
linetext[l] = yytext[l];
}
if (l > 0 && yytext[l-1] == '<')
{
type = TrailingComment;
}
for (;;)
{
if (c2 == 0 || c2 == EOF)
......@@ -5159,13 +5162,17 @@ void doxygen_comment()
{
i = base;
l -= base;
addCommentLine(&linetext[i], l, DoxygenComment);
addCommentLine(&linetext[i], l, type);
}
else if (!isfirstline && (c1 != '*' || c2 != '/'))
else if (c1 != '*' || c2 != '/')
{
addCommentLine("", 0, DoxygenComment);
addCommentLine("", 0, type);
}
if (isfirstline)
{
isfirstline = 0;
base = 256;
}
isfirstline = 0;
l = 0;
if (c1 == '*' && c2 == '/')
{
......@@ -5176,51 +5183,40 @@ void doxygen_comment()
}
}
/*
* Called for / + **< and / + *!< doxygen trailing comments
*/
void doxygen_trailing()
{
/* add a comment to the previous entity */
skip_comment();
}
/*
* Called for //! and /// doxygen comments (handles just one line)
*/
void doxygen_cpp_comment()
{
int type = DoxygenComment;
size_t pos = 2;
while (yytext[pos-2] != '/' || yytext[pos-1] != '/') pos++;
while (pos < yyleng && yytext[pos-1] == '/' && yytext[pos] == '/') pos++;
if (pos < yyleng && yytext[pos] == '!') pos++;
addCommentLine(&yytext[pos], yyleng - pos, DoxygenComment);
}
/*
* Called for / + **< and / + *!< doxygen trailing comments
*/
void doxygen_cpp_trailing()
{
/* add a comment to the previous entity */
if (pos < yyleng && yytext[pos] == '<')
{
pos++;
type = TrailingComment;
}
addCommentLine(&yytext[pos], yyleng - pos, type);
}
/*
* Called for // + *{
* Called for //@{
*/
void doxygen_group_start()
{
/* Set the "ingroup" marker */
setCommentGroup(1);
setCommentMemberGroup(1);
}
/*
* Called for // + *}
* Called for //@}
*/
void doxygen_group_end()
{
/* Clear the "ingroup" marker */
setCommentGroup(0);
setCommentMemberGroup(0);
}
/*
......@@ -5242,7 +5238,8 @@ void vtk_name_comment()
pos++;
}
pos++;
data->NameComment = vtkstrndup(&yytext[pos], yyleng - pos);
setCommentState(NameComment);
addCommentLine(&yytext[pos], yyleng - pos, NormalComment);
}
/*
......@@ -5789,26 +5786,30 @@ void preprocessor_directive(const char *text, size_t l)
exit(1);
}
}
else if (n == 6 && strncmp(directive, "define", n) == 0 &&
ep - cp > 4 && strncmp(cp, "VTK", 3) == 0)
else if (n == 6 && strncmp(directive, "define", n) == 0)
{
/* macros that start with "VTK" */
MacroInfo *macro;
macro = vtkParsePreprocess_GetMacro(preprocessor, cp);
if (macro && macro->Definition && !macro->IsFunction)
closeComment();
if (ep - cp > 4 && strncmp(cp, "VTK", 3) == 0)
{
/* if macro evaluates to a constant, add it as a constant */
macro->IsExcluded = 1;
if (guess_constant_type(macro->Definition) == 0)
{
result = VTK_PARSE_MACRO_UNDEFINED;
}
macro->IsExcluded = 0;
if (result < VTK_PARSE_MACRO_UNDEFINED)
/* macros that start with "VTK" */
MacroInfo *macro;
macro = vtkParsePreprocess_GetMacro(preprocessor, cp);
if (macro && macro->Definition && !macro->IsFunction)
{
add_constant(
vtkstrdup(macro->Name), vtkstrdup(macro->Definition), 0, NULL, 1);
/* if macro evaluates to a constant, add it as a constant */
macro->IsExcluded = 1;
if (guess_constant_type(macro->Definition) == 0)
{
result = VTK_PARSE_MACRO_UNDEFINED;
}
macro->IsExcluded = 0;
if (result < VTK_PARSE_MACRO_UNDEFINED)
{
add_constant(
vtkstrdup(macro->Name), vtkstrdup(macro->Definition),
0, NULL, 1);
}
}
}
}
......
......@@ -60,9 +60,7 @@ static int skip_to_next_directive();
static int skip_conditional_block();
static void doxygen_comment();
static void doxygen_trailing();
static void doxygen_cpp_comment();
static void doxygen_cpp_trailing();
static void doxygen_group_start();
static void doxygen_group_end();
static void vtk_comment();
......@@ -95,7 +93,7 @@ ID [a-zA-Z_\x80-\xff][0-9a-zA-Z_\x80-\xff]*
%%
"/*"[*!]"<" { doxygen_trailing(); }
"/*"[*!]"<" { doxygen_comment(); }
^[\t ]*"/*"[*!] { doxygen_comment(); }
......@@ -113,7 +111,7 @@ ID [a-zA-Z_\x80-\xff][0-9a-zA-Z_\x80-\xff]*
skip_ahead_until("@end");
}
"//"[/!]"<".* { doxygen_cpp_trailing(); }
"//"[/!]"<".* { doxygen_cpp_comment(); }
^[\t ]*"//"[/!].* { doxygen_cpp_comment(); }
^[\t ]*"//@{".* { doxygen_group_start(); }
......@@ -1084,19 +1082,24 @@ int skip_ahead_until(const char *text)
/*
* Called for / + ** and / + *! doxygen comments (handles entire comment)
* Called for doxygen C-style comments
*/
void doxygen_comment()
{
char linetext[256];
int savelineno = yylineno;
int asterisk, isfirstline = 1;
int type = DoxygenComment;
size_t l = 0, i = 0, base = yyleng;
int c1 = 0, c2 = input();
for (l = 0; l < yyleng; l++)
{
linetext[l] = yytext[l];
}
if (l > 0 && yytext[l-1] == '<')
{
type = TrailingComment;
}
for (;;)
{
if (c2 == 0 || c2 == EOF)
......@@ -1152,13 +1155,17 @@ void doxygen_comment()
{
i = base;
l -= base;
addCommentLine(&linetext[i], l, DoxygenComment);
addCommentLine(&linetext[i], l, type);
}
else if (c1 != '*' || c2 != '/')
{
addCommentLine("", 0, type);
}
else if (!isfirstline && (c1 != '*' || c2 != '/'))
if (isfirstline)
{
addCommentLine("", 0, DoxygenComment);
isfirstline = 0;
base = 256;
}
isfirstline = 0;
l = 0;
if (c1 == '*' && c2 == '/')
{
......@@ -1169,51 +1176,40 @@ void doxygen_comment()
}
}
/*
* Called for / + **< and / + *!< doxygen trailing comments
*/
void doxygen_trailing()
{
/* add a comment to the previous entity */
skip_comment();
}
/*
* Called for //! and /// doxygen comments (handles just one line)
*/
void doxygen_cpp_comment()
{
int type = DoxygenComment;
size_t pos = 2;
while (yytext[pos-2] != '/' || yytext[pos-1] != '/') pos++;
while (pos < yyleng && yytext[pos-1] == '/' && yytext[pos] == '/') pos++;
if (pos < yyleng && yytext[pos] == '!') pos++;
addCommentLine(&yytext[pos], yyleng - pos, DoxygenComment);
}
/*
* Called for / + **< and / + *!< doxygen trailing comments
*/
void doxygen_cpp_trailing()
{
/* add a comment to the previous entity */
if (pos < yyleng && yytext[pos] == '<')
{
pos++;
type = TrailingComment;
}
addCommentLine(&yytext[pos], yyleng - pos, type);
}
/*
* Called for // + *{
* Called for //@{
*/
void doxygen_group_start()
{
/* Set the "ingroup" marker */
setCommentGroup(1);
setCommentMemberGroup(1);
}
/*
* Called for // + *}
* Called for //@}
*/
void doxygen_group_end()
{
/* Clear the "ingroup" marker */
setCommentGroup(0);
setCommentMemberGroup(0);
}
/*
......@@ -1235,7 +1231,8 @@ void vtk_name_comment()
pos++;
}
pos++;
data->NameComment = vtkstrndup(&yytext[pos], yyleng - pos);
setCommentState(NameComment);
addCommentLine(&yytext[pos], yyleng - pos, NormalComment);
}
/*
......@@ -1782,26 +1779,30 @@ void preprocessor_directive(const char *text, size_t l)
exit(1);
}
}
else if (n == 6 && strncmp(directive, "define", n) == 0 &&
ep - cp > 4 && strncmp(cp, "VTK", 3) == 0)
else if (n == 6 && strncmp(directive, "define", n) == 0)
{
/* macros that start with "VTK" */
MacroInfo *macro;
macro = vtkParsePreprocess_GetMacro(preprocessor, cp);
if (macro && macro->Definition && !macro->IsFunction)
closeComment();
if (ep - cp > 4 && strncmp(cp, "VTK", 3) == 0)
{
/* if macro evaluates to a constant, add it as a constant */
macro->IsExcluded = 1;
if (guess_constant_type(macro->Definition) == 0)
{
result = VTK_PARSE_MACRO_UNDEFINED;
}
macro->IsExcluded = 0;
if (result < VTK_PARSE_MACRO_UNDEFINED)
/* macros that start with "VTK" */
MacroInfo *macro;
macro = vtkParsePreprocess_GetMacro(preprocessor, cp);
if (macro && macro->Definition && !macro->IsFunction)
{
add_constant(
vtkstrdup(macro->Name), vtkstrdup(macro->Definition), 0, NULL, 1);
/* if macro evaluates to a constant, add it as a constant */
macro->IsExcluded = 1;
if (guess_constant_type(macro->Definition) == 0)
{
result = VTK_PARSE_MACRO_UNDEFINED;
}
macro->IsExcluded = 0;
if (result < VTK_PARSE_MACRO_UNDEFINED)
{
add_constant(
vtkstrdup(macro->Name), vtkstrdup(macro->Definition),
0, NULL, 1);
}
}
}
}
......
This diff is collapsed.
......@@ -384,11 +384,12 @@ enum comment_enum
StickyComment = -1,
NoComment = 0,
NormalComment = 1,
DescriptionComment = 2,
SeeAlsoComment = 3,
CaveatsComment = 4,
DoxygenComment = 5,
UnwantedComment = 6
NameComment = 2,
DescriptionComment = 3,
SeeAlsoComment = 4,
CaveatsComment = 5,
DoxygenComment = 6,
TrailingComment = 7
};
/* "private" variables */
......@@ -396,36 +397,50 @@ char *commentText = NULL;
size_t commentLength = 0;
size_t commentAllocatedLength = 0;
int commentState = 0;
int commentGroup = 0;
int commentMemberGroup = 0;
int commentGroupDepth = 0;
parse_dox_t commentType = DOX_COMMAND_OTHER;
const char *commentTarget = NULL;
/* Struct for recognizing certain doxygen commands */
struct DoxygenCommandInfo
{
const char *name;
size_t length;
int type;
parse_dox_t type;
};
/* List of doxygen commands (for now, just list ones to skip) */
/* List of doxygen commands (@cond is not handled yet) */
struct DoxygenCommandInfo doxygenCommands[] = {
{ "def", 3, 0 },
{ "defgroup", 8, 0 },
{ "example", 7, 0 },
{ "file", 4, 0 },
{ "internal", 8, 0 },
{ "mainpage", 8, 0 },
{ "name", 4, 0 },
{ "page", 4, 0 },
{ "privatesection", 14, 0 },
{ "protectedsection", 16, 0 },
{ "publicsection", 13, 0 },
{ "subpage", 7, 0 },
{ "tableofcontents", 15, 0 },
{ "section", 7, 0 },
{ "subsection", 10, 0 },
{ "subsubsection", 13, 0 },
{ "paragraph", 9, 0 },
{ NULL, 0, 0 }
{ "def", 3, DOX_COMMAND_DEF },
{ "category", 8, DOX_COMMAND_CATEGORY },
{ "interface", 9, DOX_COMMAND_INTERFACE },
{ "protocol", 8, DOX_COMMAND_PROTOCOL },
{ "class", 5, DOX_COMMAND_CLASS },
{ "enum", 4, DOX_COMMAND_ENUM },
{ "struct", 6, DOX_COMMAND_STRUCT },
{ "union", 5, DOX_COMMAND_UNION },
{ "namespace", 9, DOX_COMMAND_NAMESPACE },
{ "typedef", 7, DOX_COMMAND_TYPEDEF },
{ "fn", 2, DOX_COMMAND_FN },
{ "property", 8, DOX_COMMAND_PROPERTY },
{ "var", 3, DOX_COMMAND_VAR },
{ "name", 4, DOX_COMMAND_NAME },
{ "defgroup", 8, DOX_COMMAND_DEFGROUP },
{ "addtogroup", 10, DOX_COMMAND_ADDTOGROUP },
{ "weakgroup", 9, DOX_COMMAND_WEAKGROUP },
{ "example", 7, DOX_COMMAND_EXAMPLE },
{ "file", 4, DOX_COMMAND_FILE },
{ "dir", 3, DOX_COMMAND_DIR },
{ "mainpage", 8, DOX_COMMAND_MAINPAGE },
{ "page", 4, DOX_COMMAND_PAGE },
{ "subpage", 7, DOX_COMMAND_SUBPAGE },
{ "internal", 8, DOX_COMMAND_INTERNAL },
{ "package", 7, DOX_COMMAND_PACKAGE },
{ "privatesection", 14, DOX_COMMAND_PRIVATESECTION },
{ "protectedsection", 16, DOX_COMMAND_PROTECTEDSECTION },
{ "publicsection", 13, DOX_COMMAND_PUBLICSECTION },
{ NULL, 0, DOX_COMMAND_OTHER }
};
void closeComment();
......@@ -439,6 +454,7 @@ void clearComment()
commentText[commentLength] = '\0';
}
commentState = 0;
commentType = DOX_COMMAND_OTHER;
}
/* This is called when entering or leaving a comment block */
......@@ -494,7 +510,7 @@ const char *getComment()
}
/* Check for doxygen commands that mark unwanted comments */
int checkDoxygenCommand(const char *text, size_t n)
parse_dox_t checkDoxygenCommand(const char *text, size_t n)
{
struct DoxygenCommandInfo *info;
for (info = doxygenCommands; info->name; info++)
......@@ -504,13 +520,14 @@ int checkDoxygenCommand(const char *text, size_t n)
return info->type;
}
}
return 1;
return DOX_COMMAND_OTHER;
}
/* This is called whenever a comment line is encountered */
void addCommentLine(const char *line, size_t n, int type)
{
size_t i, j;
parse_dox_t t = DOX_COMMAND_OTHER;
if (type == DoxygenComment || commentState == DoxygenComment)
{
......@@ -526,11 +543,38 @@ void addCommentLine(const char *line, size_t n, int type)
{
i++;
}
if (checkDoxygenCommand(&line[j], i-j) == 0 ||
(line[i-1] == '@' && (line[i] == '{' || line[i] == '}')))
if (line[i-1] == '@' && (line[i] == '{' || line[i] == '}'))
{
/* skip this comment block */
commentState = UnwantedComment;
if (line[i] == '{')
{
commentGroupDepth++;
}
else
{
--commentGroupDepth;
}
closeComment();
return;
}
else
{
/* record the type of this comment */
t = checkDoxygenCommand(&line[j], i-j);
if (t != DOX_COMMAND_OTHER)
{
while (i < n && line[i] == ' ')
{
i++;
}
j = i;
while (i < n && vtkParse_CharType(line[i], CPRE_XID))
{
i++;
}
commentTarget = vtkstrndup(&line[j], i-j);
/* remove this line from the comment */
n = 0;
}
}
}
}
......@@ -539,15 +583,25 @@ void addCommentLine(const char *line, size_t n, int type)
{
return;
}
if (commentState != type && commentState != UnwantedComment)
if (commentState != type)
{
setCommentState(type);
}
if (t != DOX_COMMAND_OTHER)
{
commentType = t;
}
}
else if (type == TrailingComment)
{
if (commentState != type)
{
setCommentState(type);
}
}
else if (commentState == 0 ||
commentState == StickyComment ||
commentState == ClosedComment ||
commentState == UnwantedComment)
commentState == ClosedComment)
{
clearComment();
return;
......@@ -580,9 +634,88 @@ void addCommentLine(const char *line, size_t n, int type)
commentText[commentLength] = '\0';
}
/* Store a doxygen comment */
void storeComment()
{
CommentInfo *info = (CommentInfo *)malloc(sizeof(CommentInfo));
vtkParse_InitComment(info);
info->Type = commentType;
info->Name = commentTarget;
info->Comment = vtkstrdup(getComment());
if (commentType >= DOX_COMMAND_DEFGROUP)
{
/* comment has no scope, it is global to the project */
vtkParse_AddCommentToNamespace(data->Contents, info);
}
else
{
/* comment is scoped to current namespace */
if (currentClass)
{
vtkParse_AddCommentToClass(currentClass, info);
}
else
{
vtkParse_AddCommentToNamespace(currentNamespace, info);
}
}
}
/* Apply a doxygen trailing comment to the previous item */
void applyComment(ClassInfo *cls)
{
int i;
ItemInfo *item;
const char *comment = vtkstrdup(getComment());
i = cls->NumberOfItems;
if (i > 0)
{
item = &cls->Items[--i];
if (item->Type == VTK_NAMESPACE_INFO)
{
cls->Namespaces[item->Index]->Comment = comment;
}
else if (item->Type == VTK_CLASS_INFO ||
item->Type == VTK_STRUCT_INFO ||
item->Type == VTK_UNION_INFO)
{
cls->Classes[item->Index]->Comment = comment;
}
else if (item->Type == VTK_ENUM_INFO)
{
cls->Enums[item->Index]->Comment = comment;
}
else if (item->Type == VTK_FUNCTION_INFO)
{
cls->Functions[item->Index]->Comment = comment;
}
else if (item->Type == VTK_VARIABLE_INFO)
{
cls->Variables[item->Index]->Comment = comment;
}
else if (item->Type == VTK_CONSTANT_INFO)
{