From 327423e217337bf4e64515aba6cf78b9877bc165 Mon Sep 17 00:00:00 2001 From: Dimitri van Heesch Date: Fri, 17 Jul 2020 16:13:38 +0200 Subject: issue #7852, #7867, #7901: Changed the set of commands that effect ending a brief description --- src/commentscan.l | 296 +++++++++++++++++++++++----------------------- src/groupdef.cpp | 5 + testing/019/group__g1.xml | 2 +- testing/019/group__g2.xml | 2 +- testing/019/group__g3.xml | 2 +- testing/019_defgroup.c | 2 +- 6 files changed, 159 insertions(+), 150 deletions(-) diff --git a/src/commentscan.l b/src/commentscan.l index 12391cb..aa80028 100644 --- a/src/commentscan.l +++ b/src/commentscan.l @@ -145,156 +145,163 @@ static const char *stateToString(int state); typedef bool (*DocCmdFunc)(yyscan_t yyscanner,const QCString &name, const QCStringList &optList); +enum class CommandSpacing +{ + Invisible, // command sets some property but does not appear in the output. + Inline, // command appears inline in the output which can be a brief description. + Block // command starts a new paragraphs / ends a brief description. +}; + struct DocCmdMap { - DocCmdMap(DocCmdFunc h,bool b) : handler(h), endsBrief(b) {} + DocCmdMap(DocCmdFunc h,CommandSpacing s) : handler(h), spacing(s) {} DocCmdFunc handler; - bool endsBrief; + CommandSpacing spacing; }; // map of command to handler function static const std::map< std::string, DocCmdMap > docCmdMap = { - // command name handler function ends brief description - { "brief", { &handleBrief, FALSE }}, - { "short", { &handleBrief, FALSE }}, - { "fn", { &handleFn, TRUE }}, - { "var", { &handleFn, TRUE }}, - { "typedef", { &handleFn, TRUE }}, - { "property", { &handleFn, TRUE }}, - { "def", { &handleDef, TRUE }}, - { "overload", { &handleOverload, FALSE }}, - { "enum", { &handleEnum, TRUE }}, - { "defgroup", { &handleDefGroup, TRUE }}, - { "addtogroup", { &handleAddToGroup, TRUE }}, - { "weakgroup", { &handleWeakGroup, TRUE }}, - { "namespace", { &handleNamespace, TRUE }}, - { "package", { &handlePackage, TRUE }}, - { "class", { &handleClass, TRUE }}, - { "headerfile", { &handleHeaderFile, FALSE }}, - { "protocol", { &handleProtocol, TRUE }}, - { "category", { &handleCategory, TRUE }}, - { "union", { &handleUnion, TRUE }}, - { "struct", { &handleStruct, TRUE }}, - { "interface", { &handleInterface, TRUE }}, - { "idlexcept", { &handleIdlException, TRUE }}, - { "page", { &handlePage, TRUE }}, - { "mainpage", { &handleMainpage, TRUE }}, - { "file", { &handleFile, TRUE }}, - { "dir", { &handleDir, TRUE }}, - { "example", { &handleExample, FALSE }}, - { "details", { &handleDetails, TRUE }}, - { "name", { &handleName, FALSE }}, - { "todo", { &handleTodo, FALSE }}, // end brief will be done differently - { "test", { &handleTest, FALSE }}, // end brief will be done differently - { "bug", { &handleBug, FALSE }}, // end brief will be done differently - { "deprecated", { &handleDeprecated, FALSE }}, // end brief will be done differently - { "xrefitem", { &handleXRefItem, FALSE }}, // end brief will be done differently - { "related", { &handleRelated, TRUE }}, - { "relates", { &handleRelated, TRUE }}, - { "relatedalso", { &handleRelatedAlso, TRUE }}, - { "relatesalso", { &handleRelatedAlso, TRUE }}, - { "parblock", { &handleParBlock, TRUE }}, - { "endparblock", { &handleEndParBlock, TRUE }}, - { "refitem", { &handleRefItem, TRUE }}, - { "cite", { &handleCite, FALSE }}, - { "subpage", { &handleSubpage, TRUE }}, - { "section", { &handleSection, TRUE }}, - { "subsection", { &handleSection, TRUE }}, - { "subsubsection", { &handleSection, TRUE }}, - { "paragraph", { &handleSection, TRUE }}, - { "anchor", { &handleAnchor, TRUE }}, - { "verbatim", { &handleFormatBlock, TRUE }}, - { "latexonly", { &handleFormatBlock, FALSE }}, - { "htmlonly", { &handleFormatBlock, FALSE }}, - { "xmlonly", { &handleFormatBlock, FALSE }}, - { "docbookonly", { &handleFormatBlock, FALSE }}, - { "rtfonly", { &handleFormatBlock, FALSE }}, - { "manonly", { &handleFormatBlock, FALSE }}, - { "dot", { &handleFormatBlock, TRUE }}, - { "msc", { &handleFormatBlock, TRUE }}, - { "startuml", { &handleFormatBlock, TRUE }}, - { "code", { &handleFormatBlock, TRUE }}, - { "addindex", { &handleAddIndex, FALSE }}, - { "if", { &handleIf, FALSE }}, - { "ifnot", { &handleIfNot, FALSE }}, - { "elseif", { &handleElseIf, FALSE }}, - { "else", { &handleElse, FALSE }}, - { "endif", { &handleEndIf, FALSE }}, - { "ingroup", { &handleIngroup, TRUE }}, - { "nosubgrouping", { &handleNoSubGrouping, FALSE }}, - { "showinitializer", { &handleShowInitializer, FALSE }}, - { "hideinitializer", { &handleHideInitializer, FALSE }}, - { "callgraph", { &handleCallgraph, FALSE }}, - { "hidecallgraph", { &handleHideCallgraph, FALSE }}, - { "callergraph", { &handleCallergraph, FALSE }}, - { "hidecallergraph", { &handleHideCallergraph, FALSE }}, - { "showrefby", { &handleReferencedByRelation, FALSE }}, - { "hiderefby", { &handleHideReferencedByRelation, FALSE }}, - { "showrefs", { &handleReferencesRelation, FALSE }}, - { "hiderefs", { &handleHideReferencesRelation, FALSE }}, - { "internal", { &handleInternal, TRUE }}, - { "_linebr", { &handleLineBr, FALSE }}, - { "static", { &handleStatic, FALSE }}, - { "pure", { &handlePure, FALSE }}, - { "private", { &handlePrivate, FALSE }}, - { "privatesection", { &handlePrivateSection, FALSE }}, - { "protected", { &handleProtected, FALSE }}, - { "protectedsection",{ &handleProtectedSection, FALSE }}, - { "public", { &handlePublic, FALSE }}, - { "publicsection", { &handlePublicSection, FALSE }}, - { "tableofcontents", { &handleToc, FALSE }}, - { "inherit", { &handleInherit, TRUE }}, - { "extends", { &handleExtends, TRUE }}, - { "implements", { &handleExtends, TRUE }}, - { "memberof", { &handleMemberOf, TRUE }}, - { "arg", { 0, TRUE }}, - { "attention", { 0, TRUE }}, - { "author", { 0, TRUE }}, - { "authors", { 0, TRUE }}, - { "copydoc", { &handleCopyDoc, TRUE }}, - { "copybrief", { &handleCopyBrief, FALSE }}, - { "copydetails", { &handleCopyDetails, TRUE }}, - { "copyright", { 0, TRUE }}, - { "date", { 0, TRUE }}, - { "dotfile", { 0, TRUE }}, - { "htmlinclude", { 0, FALSE }}, - { "image", { 0, TRUE }}, - { "include", { 0, TRUE }}, - { "includelineno", { 0, TRUE }}, - { "invariant", { 0, TRUE }}, - { "latexinclude", { 0, FALSE }}, - { "li", { 0, TRUE }}, - { "line", { 0, TRUE }}, - { "note", { 0, TRUE }}, - { "par", { 0, TRUE }}, - { "param", { &handleParam, TRUE }}, - { "tparam", { 0, TRUE }}, - { "post", { 0, TRUE }}, - { "pre", { 0, TRUE }}, - { "remark", { 0, TRUE }}, - { "remarks", { 0, TRUE }}, - { "result", { 0, TRUE }}, - { "return", { 0, TRUE }}, - { "returns", { 0, TRUE }}, - { "exception", { 0, TRUE }}, - { "retval", { &handleRetval, TRUE }}, - { "sa", { 0, TRUE }}, - { "see", { 0, TRUE }}, - { "since", { 0, TRUE }}, - { "throw", { 0, TRUE }}, - { "throws", { 0, TRUE }}, - { "until", { 0, TRUE }}, - { "verbinclude", { 0, FALSE }}, - { "version", { 0, TRUE }}, - { "warning", { 0, TRUE }}, - { "snippet", { 0, TRUE }}, - { "snippetlineno", { 0, TRUE }}, - { "noop", { &handleNoop, TRUE }}, - { "rtfinclude", { 0, FALSE }}, - { "docbookinclude", { 0, FALSE }}, - { "maninclude", { 0, FALSE }}, - { "xmlinclude", { 0, FALSE }} + // command name handler function command spacing + { "_linebr", { &handleLineBr, CommandSpacing::Inline }}, + { "addindex", { &handleAddIndex, CommandSpacing::Invisible }}, + { "addtogroup", { &handleAddToGroup, CommandSpacing::Invisible }}, + { "anchor", { &handleAnchor, CommandSpacing::Invisible }}, + { "arg", { 0, CommandSpacing::Block }}, + { "attention", { 0, CommandSpacing::Block }}, + { "author", { 0, CommandSpacing::Block }}, + { "authors", { 0, CommandSpacing::Block }}, + { "brief", { &handleBrief, CommandSpacing::Invisible }}, + { "bug", { &handleBug, CommandSpacing::Block }}, + { "callergraph", { &handleCallergraph, CommandSpacing::Invisible }}, + { "callgraph", { &handleCallgraph, CommandSpacing::Invisible }}, + { "category", { &handleCategory, CommandSpacing::Invisible }}, + { "cite", { &handleCite, CommandSpacing::Inline }}, + { "class", { &handleClass, CommandSpacing::Invisible }}, + { "code", { &handleFormatBlock, CommandSpacing::Block }}, + { "copybrief", { &handleCopyBrief, CommandSpacing::Invisible }}, + { "copydetails", { &handleCopyDetails, CommandSpacing::Block }}, + { "copydoc", { &handleCopyDoc, CommandSpacing::Block }}, + { "copyright", { 0, CommandSpacing::Block }}, + { "date", { 0, CommandSpacing::Block }}, + { "def", { &handleDef, CommandSpacing::Invisible }}, + { "defgroup", { &handleDefGroup, CommandSpacing::Invisible }}, + { "deprecated", { &handleDeprecated, CommandSpacing::Block }}, + { "details", { &handleDetails, CommandSpacing::Block }}, + { "dir", { &handleDir, CommandSpacing::Invisible }}, + { "docbookinclude", { 0, CommandSpacing::Inline }}, + { "docbookonly", { &handleFormatBlock, CommandSpacing::Invisible }}, + { "dot", { &handleFormatBlock, CommandSpacing::Block }}, + { "dotfile", { 0, CommandSpacing::Block }}, + { "else", { &handleElse, CommandSpacing::Inline }}, + { "elseif", { &handleElseIf, CommandSpacing::Inline }}, + { "endif", { &handleEndIf, CommandSpacing::Inline }}, + { "endparblock", { &handleEndParBlock, CommandSpacing::Block }}, + { "enum", { &handleEnum, CommandSpacing::Invisible }}, + { "example", { &handleExample, CommandSpacing::Invisible }}, + { "exception", { 0, CommandSpacing::Block }}, + { "extends", { &handleExtends, CommandSpacing::Invisible }}, + { "file", { &handleFile, CommandSpacing::Invisible }}, + { "fn", { &handleFn, CommandSpacing::Invisible }}, + { "headerfile", { &handleHeaderFile, CommandSpacing::Invisible }}, + { "hidecallergraph", { &handleHideCallergraph, CommandSpacing::Invisible }}, + { "hidecallgraph", { &handleHideCallgraph, CommandSpacing::Invisible }}, + { "hideinitializer", { &handleHideInitializer, CommandSpacing::Invisible }}, + { "hiderefby", { &handleHideReferencedByRelation, CommandSpacing::Invisible }}, + { "hiderefs", { &handleHideReferencesRelation, CommandSpacing::Invisible }}, + { "htmlinclude", { 0, CommandSpacing::Inline }}, + { "htmlonly", { &handleFormatBlock, CommandSpacing::Invisible }}, + { "idlexcept", { &handleIdlException, CommandSpacing::Invisible }}, + { "if", { &handleIf, CommandSpacing::Inline }}, + { "ifnot", { &handleIfNot, CommandSpacing::Inline }}, + { "image", { 0, CommandSpacing::Block }}, + { "implements", { &handleExtends, CommandSpacing::Invisible }}, + { "include", { 0, CommandSpacing::Block }}, + { "includelineno", { 0, CommandSpacing::Block }}, + { "ingroup", { &handleIngroup, CommandSpacing::Invisible }}, + { "inherit", { &handleInherit, CommandSpacing::Invisible }}, + { "interface", { &handleInterface, CommandSpacing::Invisible }}, + { "internal", { &handleInternal, CommandSpacing::Block }}, + { "invariant", { 0, CommandSpacing::Block }}, + { "latexinclude", { 0, CommandSpacing::Inline }}, + { "latexonly", { &handleFormatBlock, CommandSpacing::Invisible }}, + { "li", { 0, CommandSpacing::Block }}, + { "line", { 0, CommandSpacing::Invisible }}, + { "mainpage", { &handleMainpage, CommandSpacing::Invisible }}, + { "maninclude", { 0, CommandSpacing::Inline }}, + { "manonly", { &handleFormatBlock, CommandSpacing::Invisible }}, + { "memberof", { &handleMemberOf, CommandSpacing::Invisible }}, + { "msc", { &handleFormatBlock, CommandSpacing::Block }}, + { "name", { &handleName, CommandSpacing::Invisible }}, + { "namespace", { &handleNamespace, CommandSpacing::Invisible }}, + { "noop", { &handleNoop, CommandSpacing::Invisible }}, + { "nosubgrouping", { &handleNoSubGrouping, CommandSpacing::Invisible }}, + { "note", { 0, CommandSpacing::Block }}, + { "overload", { &handleOverload, CommandSpacing::Invisible }}, + { "package", { &handlePackage, CommandSpacing::Invisible }}, + { "page", { &handlePage, CommandSpacing::Invisible }}, + { "par", { 0, CommandSpacing::Block }}, + { "paragraph", { &handleSection, CommandSpacing::Block }}, + { "param", { &handleParam, CommandSpacing::Block }}, + { "parblock", { &handleParBlock, CommandSpacing::Block }}, + { "post", { 0, CommandSpacing::Block }}, + { "pre", { 0, CommandSpacing::Block }}, + { "private", { &handlePrivate, CommandSpacing::Invisible }}, + { "privatesection", { &handlePrivateSection, CommandSpacing::Invisible }}, + { "property", { &handleFn, CommandSpacing::Invisible }}, + { "protected", { &handleProtected, CommandSpacing::Invisible }}, + { "protectedsection",{ &handleProtectedSection, CommandSpacing::Invisible }}, + { "protocol", { &handleProtocol, CommandSpacing::Invisible }}, + { "public", { &handlePublic, CommandSpacing::Invisible }}, + { "publicsection", { &handlePublicSection, CommandSpacing::Invisible }}, + { "pure", { &handlePure, CommandSpacing::Invisible }}, + { "refitem", { &handleRefItem, CommandSpacing::Inline }}, + { "related", { &handleRelated, CommandSpacing::Invisible }}, + { "relatedalso", { &handleRelatedAlso, CommandSpacing::Invisible }}, + { "relates", { &handleRelated, CommandSpacing::Invisible }}, + { "relatesalso", { &handleRelatedAlso, CommandSpacing::Invisible }}, + { "remark", { 0, CommandSpacing::Block }}, + { "remarks", { 0, CommandSpacing::Block }}, + { "result", { 0, CommandSpacing::Block }}, + { "return", { 0, CommandSpacing::Block }}, + { "returns", { 0, CommandSpacing::Block }}, + { "retval", { &handleRetval, CommandSpacing::Block }}, + { "rtfinclude", { 0, CommandSpacing::Inline }}, + { "rtfonly", { &handleFormatBlock, CommandSpacing::Invisible }}, + { "sa", { 0, CommandSpacing::Block }}, + { "section", { &handleSection, CommandSpacing::Block }}, + { "see", { 0, CommandSpacing::Block }}, + { "short", { &handleBrief, CommandSpacing::Invisible }}, + { "showinitializer", { &handleShowInitializer, CommandSpacing::Invisible }}, + { "showrefby", { &handleReferencedByRelation, CommandSpacing::Invisible }}, + { "showrefs", { &handleReferencesRelation, CommandSpacing::Invisible }}, + { "since", { 0, CommandSpacing::Block }}, + { "snippet", { 0, CommandSpacing::Block }}, + { "snippetlineno", { 0, CommandSpacing::Block }}, + { "startuml", { &handleFormatBlock, CommandSpacing::Block }}, + { "static", { &handleStatic, CommandSpacing::Invisible }}, + { "struct", { &handleStruct, CommandSpacing::Invisible }}, + { "subpage", { &handleSubpage, CommandSpacing::Inline }}, + { "subsection", { &handleSection, CommandSpacing::Block }}, + { "subsubsection", { &handleSection, CommandSpacing::Block }}, + { "tableofcontents", { &handleToc, CommandSpacing::Invisible }}, + { "test", { &handleTest, CommandSpacing::Block }}, + { "throw", { 0, CommandSpacing::Block }}, + { "throws", { 0, CommandSpacing::Block }}, + { "todo", { &handleTodo, CommandSpacing::Block }}, + { "tparam", { 0, CommandSpacing::Block }}, + { "typedef", { &handleFn, CommandSpacing::Invisible }}, + { "union", { &handleUnion, CommandSpacing::Invisible }}, + { "until", { 0, CommandSpacing::Block }}, + { "var", { &handleFn, CommandSpacing::Invisible }}, + { "verbatim", { &handleFormatBlock, CommandSpacing::Block }}, + { "verbinclude", { 0, CommandSpacing::Inline }}, + { "version", { 0, CommandSpacing::Block }}, + { "warning", { 0, CommandSpacing::Block }}, + { "weakgroup", { &handleWeakGroup, CommandSpacing::Invisible }}, + { "xmlinclude", { 0, CommandSpacing::Inline }}, + { "xmlonly", { &handleFormatBlock, CommandSpacing::Invisible }}, + { "xrefitem", { &handleXRefItem, CommandSpacing::Block }} }; #define YY_NO_INPUT 1 @@ -665,7 +672,7 @@ RCSTAG "$"{ID}":"[^\n$]+"$" int i=0; while (yytext[i]==' ' || yytext[i]=='\t') i++; yyextra->spaceBeforeCmd = QCString(yytext).left(i); - if (it->second.endsBrief && !(yyextra->inContext==OutputXRef && cmdName=="parblock")) + if (it->second.spacing==CommandSpacing::Block && !(yyextra->inContext==OutputXRef && cmdName=="parblock")) { yyextra->briefEndsAtDot=FALSE; // this command forces the end of brief description @@ -1906,7 +1913,6 @@ static bool handleDefGroup(yyscan_t yyscanner,const QCString &, const QCStringLi struct yyguts_t *yyg = (struct yyguts_t*)yyscanner; bool stop=makeStructuralIndicator(yyscanner,Entry::GROUPDOC_SEC); yyextra->current->groupDocType = Entry::GROUPDOC_NORMAL; - setOutput(yyscanner,OutputBrief); BEGIN( GroupDocArg1 ); return stop; } @@ -2523,7 +2529,6 @@ static bool handleLineBr(yyscan_t yyscanner,const QCString &, const QCStringList static bool handleStatic(yyscan_t yyscanner,const QCString &, const QCStringList &) { struct yyguts_t *yyg = (struct yyguts_t*)yyscanner; - endBrief(yyscanner); yyextra->current->stat = TRUE; return FALSE; } @@ -2531,7 +2536,6 @@ static bool handleStatic(yyscan_t yyscanner,const QCString &, const QCStringList static bool handlePure(yyscan_t yyscanner,const QCString &, const QCStringList &) { struct yyguts_t *yyg = (struct yyguts_t*)yyscanner; - endBrief(yyscanner); yyextra->current->virt = Pure; return FALSE; } diff --git a/src/groupdef.cpp b/src/groupdef.cpp index e4cb180..9b33356 100644 --- a/src/groupdef.cpp +++ b/src/groupdef.cpp @@ -1207,6 +1207,11 @@ void GroupDefImpl::writeDocumentation(OutputList &ol) ol.pushGeneratorState(); ol.disableAllBut(OutputGenerator::Man); ol.endTitleHead(getOutputFileBase(),name()); + if (!m_title.isEmpty()) + { + ol.writeString(" - "); + ol.parseText(m_title); + } ol.popGeneratorState(); ol.endHeaderSection(); ol.startContents(); diff --git a/testing/019/group__g1.xml b/testing/019/group__g1.xml index d6807ca..d9ea16d 100644 --- a/testing/019/group__g1.xml +++ b/testing/019/group__g1.xml @@ -20,9 +20,9 @@ - Text for first group. + Text for first group. diff --git a/testing/019/group__g2.xml b/testing/019/group__g2.xml index 3514d89..9b1fc83 100644 --- a/testing/019/group__g2.xml +++ b/testing/019/group__g2.xml @@ -21,9 +21,9 @@ - Text for second group. + Text for second group. diff --git a/testing/019/group__g3.xml b/testing/019/group__g3.xml index 0f21232..d9137b0 100644 --- a/testing/019/group__g3.xml +++ b/testing/019/group__g3.xml @@ -34,9 +34,9 @@ - Text for third group. + Text for third group. diff --git a/testing/019_defgroup.c b/testing/019_defgroup.c index d42d63e..d7e440e 100644 --- a/testing/019_defgroup.c +++ b/testing/019_defgroup.c @@ -38,7 +38,7 @@ void func_g3(); /** \} */ /** \addtogroup g3 - * \{ + * \{ */ /** Another function added to the third group */ -- cgit v0.12