bug_712290 A command that will generate a warning during compilation

Added command `raisewarning` and accompanying documentation.
doxygen · Nov 30, 2021 · d708649 · d708649
1 parent 3d9881c
commit d708649
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 0 deletions.
diff --git a/doc/commands.doc b/doc/commands.doc
@@ -169,6 +169,7 @@ documentation:
 \refitem cmdpublic \\public
 \refitem cmdpublicsection \\publicsection
 \refitem cmdpure \\pure
+\refitem cmdraisewarning \\raisewarning
 \refitem cmdref \\ref
 \refitem cmdrefitem \\refitem
 \refitem cmdrelated \\related
@@ -1442,6 +1443,34 @@ contains \c TEST, or \c DEV
   All the text, including the command, till the end of the line is ignored.
   The command will most commonly be used in combination with \ref cfg_aliases "ALIASES"
   to ignore not supported commands that are present for e.g. other processing tools.
+<hr>
+\section cmdraisewarning \\raisewarning ( text to be shown as warning )
+
+  \addindex \\raisewarning
+  All the text, excluding the command, till the end of the line is is literally shown
+  as a documentation warning. The text, including the command, is removed from the output.
+  The command will most commonly be used in combination with \ref cfg_aliases "ALIASES"
+  to show a specific warning.
+  \par Example:
+\verbatim
+\raisewarning My specific warnning
+
+\warnNoDoc
+
+\warnNoDoc{My specific warnning}
+\endverbatim
+   together with:
+\verbatim
+ALIASES  = warnNoDoc="\raisewarning Missing documentation"
+ALIASES += warnNoDoc{1}="\raisewarning Incomplete documentation: \1"
+\endverbatim
+   will  result in:
+\verbatim
+   ex_1.md:1: warning: My specific warnning
+   ex_1.md:3: warning: Missing documentation
+   ex_1.md:5: warning: Incomplete documentation: My specific warnning
+\endverbatim
+
 <hr>
 \section cmdelse \\else
 

diff --git a/src/commentscan.l b/src/commentscan.l
@@ -87,6 +87,7 @@ static bool handleFile(yyscan_t yyscanner,const QCString &, const StringVector &
 static bool handleDir(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleExample(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleDetails(yyscan_t yyscanner,const QCString &, const StringVector &);
+static bool handleRaiseWarning(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleNoop(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleName(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleTodo(yyscan_t yyscanner,const QCString &, const StringVector &);
@@ -259,6 +260,7 @@ static const std::map< std::string, DocCmdMap > docCmdMap =
   { "public",          { &handlePublic,           CommandSpacing::Invisible }},
   { "publicsection",   { &handlePublicSection,    CommandSpacing::Invisible }},
   { "pure",            { &handlePure,             CommandSpacing::Invisible }},
+  { "raisewarning",    { &handleRaiseWarning,     CommandSpacing::Invisible }},
   { "refitem",         { &handleRefItem,          CommandSpacing::Inline    }},
   { "related",         { &handleRelated,          CommandSpacing::Invisible }},
   { "relatedalso",     { &handleRelatedAlso,      CommandSpacing::Invisible }},
@@ -412,6 +414,8 @@ struct commentscanYY_state
   int              prevPosition = 0;
   DocGroup         docGroup;
   bool             markdownSupport = TRUE;
+
+  QCString         raiseWarning;
 };
 
 
@@ -557,6 +561,7 @@ STopt  [^\n@\\]*
 %x      GuardExpr
 %x      CdataSection
 %x      Noop
+%x      RaiseWarning
 
 %%
 
@@ -1764,6 +1769,18 @@ STopt  [^\n@\\]*
                                         }
 <Noop>.                                 { // ignore other stuff
                                         }
+  /* ----- handle argument of raisewarning command ------- */
+<RaiseWarning>{DOCNL}                   { // end of argument
+                                          warn_doc_error(yyextra->fileName,yyextra->lineNr,
+                                                         qPrint(yyextra->raiseWarning));
+                                          yyextra->raiseWarning = "";
+                                          if (*yytext=='\n') yyextra->lineNr++;
+                                          addOutput(yyscanner,'\n');
+                                          BEGIN( Comment );
+                                        }
+<RaiseWarning>.                         { // ignore other stuff
+                                          yyextra->raiseWarning += yytext;
+                                        }
   /* ----- handle argument of ingroup command ------- */
 
 <InGroupParam>{LABELID}                 { // group id
@@ -2220,6 +2237,14 @@ static bool handleDetails(yyscan_t yyscanner,const QCString &, const StringVecto
   return FALSE;
 }
 
+static bool handleRaiseWarning(yyscan_t yyscanner,const QCString &, const StringVector &)
+{
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  yyextra->raiseWarning = "";
+  BEGIN( RaiseWarning );
+  return FALSE;
+}
+
 static bool handleNoop(yyscan_t yyscanner,const QCString &, const StringVector &)
 {
   struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;