Merge branch 'albert-github-feature/bug_includedoc_label'

doc/commands.dox

@@ -2771,14 +2771,20 @@ Commands for displaying examples
   - The `option` `local` can be used make doxygen interpret the code as if it was in the
                class or namespace in which the include command appears, rather than the global namespace.
 
-  When using option `doc`, there is an second option `raise` that can be specified to raise
+  When using option `doc`, there is also the option `raise` that can be specified to raise
   all sections found in the referenced file by a certain amount. For example 
   \verbatim
   \include{doc,raise=1} file.dox
   \endverbatim will treat any level 1 \c \\section found in `file.dox` as a level 2 \c \\subsection, and any level 2 \c \\subsection
   into a level 3 \c \\subsubsection, etc.
   Similarly, for Markdown a \c \# section will be treated as a \c \#\# section.
 
+  Furthermore, there is the option `prefix` that can be used to add a prefix
+  to each label of the included sections, so that they remain unique. For example:
+  \verbatim
+  \include{doc,prefix=fn_} file.dox
+  \endverbatim will treat e.g. `\section s1` found in `file.dox` as if it was specified as `\section fn_s1`.
+
   \note The included documentation should not have comment signs in it as they will appear
        in the documentation as well.
 
@@ -2796,12 +2802,14 @@ Commands for displaying examples
   \sa sections \ref cmdinclude "\\include{lineno}".
 
 <hr>
-\section cmdincludedoc \\includedoc <file-name>
+\section cmdincludedoc \\includedoc['{'option'}'] <file-name>
 
   \addindex \\includedoc
   This command is obsolete and is still supported for backward compatibility reasons,
   it works the same way as \ref cmdinclude "\\include{doc}"
 
+  The `option`s are the same `option`s that can be used with the `\include` when using there the option `doc`.
+
   \sa section \ref cmdinclude "\\include{doc}".
 
 <hr>
@@ -2911,7 +2919,7 @@ Commands for displaying examples
  - The `option` `local` can be used make doxygen interpret the code as if it was in the
                class or namespace in which the include command appears, rather than the global namespace.
 
- When using option `doc`, there is an second option `raise` that can be specified to raise
+ When using option `doc`, there is also the option `raise` that can be specified to raise
  all sections found in the referenced file by a certain amount. For example 
  \verbatim
  \snippet{doc,raise=1} file.dox XXX
@@ -2920,6 +2928,12 @@ Commands for displaying examples
  into a level 3 \c \\subsubsection, etc.
  Similarly, for Markdown a \c \# section will be treated as a \c \#\# section.
 
+ Furthermore, there is the option `prefix` that can be used to add a prefix
+ to each label of the included sections, so that they remain unique. For example:
+ \verbatim
+ \include{doc,prefix=fn_} file.dox
+ \endverbatim will treat e.g. `\section s1` found in `file.dox` as if it was specified as `\section fn_s1`.
+
  \note The included documentation should not have comment signs in it as they will appear
        in the documentation as well.
 
@@ -2936,12 +2950,14 @@ Commands for displaying examples
   \sa sections \ref cmdsnippet "\\snippet{lineno}"
 
 <hr>
-\section cmdsnippetdoc \\snippetdoc <file-name> ( block_id )
+\section cmdsnippetdoc \\snippetdoc['{'option'}'] <file-name> ( block_id )
 
   \addindex \\snippetdoc
   This command is obsolete and is still supported for backward compatibility reasons,
   it works the same way as \ref cmdsnippet "\\snippet{doc}"
 
+  The `option`s are the same `option`s that can be used with the `\snippet` when using there the option `doc`.
+
   \sa section \ref cmdsnippet "\\snippet{doc}" and \ref cmdinclude "\\include{doc}".
 
 <hr>

doc_internal/commands_internal.md

@@ -14,6 +14,7 @@ and the version in which they were introduced.
 \refitem cmdiline \\iline
 \refitem cmdilinebr \\ilinebr
 \refitem cmdiliteral \\iliteral
+\refitem cmdiprefix \\iprefix
 \refitem cmdiraise \\iraise
 \refitem cmdiverbatim \\iverbatim
 \endsecreflist
@@ -133,12 +134,23 @@ and the version in which they were introduced.
 \section cmdiraise \\iraise \<amount\>
   \addindex \\iraise
 
-  Internal doxygen command to increase the section level by a given amount.
-  After processing `\iraise 1` for instance, a `\section` will be treated as a `\subsection`.
+  Internal doxygen command to increase the section level by a given `amount`.
+  After processing `\iraise 1` for instance, a `\section s1` will be treated as a `\subsection s1`.
   Inserted when processing `\include{doc}` with the `raise` option.
 
 \since doxygen version 1.11.0
 
+<hr>
+\section cmdiprefix \\iprefix "<label>"
+  \addindex \\iprefix
+
+  Internal doxygen command to prefix section labels references for \c \\ref and \c \\link commands.
+  After processing `\iprefix "pf_"` for instance, a <code>\\ref s1</code> will be treated as 
+  if <code>\\ref pf_s1</code> was written.
+  Inserted internally when processing `\include{doc}` with the `prefix` option.
+
+\since doxygen version 1.11.0
+
 <hr>
 \section cmdendiverbatim \\endiverbatim
 

src/cmdmapper.cpp

@@ -155,6 +155,7 @@ static const CommandMap g_cmdMap =
   { "iliteral",      CMD_ILITERAL },
   { "endiliteral",   CMD_ENDILITERAL },
   { "ianchor" ,      CMD_IANCHOR },
+  { "iprefix" ,      CMD_IPREFIX },
 };
 
 //----------------------------------------------------------------------------

src/cmdmapper.h

@@ -156,7 +156,8 @@ enum CommandType
   CMD_DOXYCONFIG   = 126,
   CMD_IMPORTANT    = 127 | SIMPLESECT_BIT,
   CMD_SUBPARAGRAPH = 128,
-  CMD_SUBSUBPARAGRAPH = 129
+  CMD_SUBSUBPARAGRAPH = 129,
+  CMD_IPREFIX      = 130
 };
 
 enum HtmlTagType

src/commentcnv.l

@@ -81,6 +81,7 @@ struct commentcnv_FileState
   int oldFileBufPos = 0;
   int oldIncludeCtx = 0;
   int oldRaiseLvl = 0;
+  QCString oldRaiseLbl;
 };
 
 struct commentcnvYY_state
@@ -96,7 +97,9 @@ struct commentcnvYY_state
   int      readLineCtx = 0;
   int      includeCtx = 0;
   int      raiseLevel = 0;
+  QCString raiseLabel;
   int      raiseIncrement = 0;
+  QCString raisePrefix;
   bool     skip = FALSE;
   QCString fileName;
   int      lineNr = 0;
@@ -144,7 +147,7 @@ static void replaceComment(yyscan_t yyscanner,int offset);
 static void clearCommentStack(yyscan_t yyscanner);
 static bool readIncludeFile(yyscan_t yyscanner,const QCString &inc,const QCString &blockId);
 static void insertCommentStart(yyscan_t yyscanner);
-static void parseIncludeOptions(yyscan_t yyscanner,std::string_view s);
+static bool parseIncludeOptions(yyscan_t yyscanner,std::string_view s);
 
 #undef  YY_INPUT
 #define YY_INPUT(buf,result,max_size) result=yyread(yyscanner,buf,max_size);
@@ -214,7 +217,7 @@ FILEMASK  {VFILEMASK}|{HFILEMASK}
 B         [ \t]
 ID        [$a-z_A-Z\x80-\xFF][$a-z_A-Z0-9\x80-\xFF]*
 
-OPTS      (","{B}*{ID}{B}*("="{B}*({ID}|[0-9]*){B}*)?)*
+OPTS      "{"[^}]*"}"{B}*
 
   //- end: NUMBER ---------------------------------------------------------------------------
 
@@ -1033,7 +1036,7 @@ SLASHopt [/]*
 				     copyToOutput(yyscanner,yytext,yyleng);
   				   }
 
-<CComment,ReadLine,IncludeFile>{B}{B}{B}{B}[\\@]("include{"{B}*"doc"{B}*{OPTS}"}"|"includedoc") { // Markdown code section
+<CComment,ReadLine,IncludeFile>{B}{B}{B}{B}[\\@]("include"{OPTS}|"includedoc"{OPTS}*) { // Markdown code section
                                      if (Config_getBool(MARKDOWN_SUPPORT))
                                      {
 				       copyToOutput(yyscanner,yytext,yyleng);
@@ -1043,7 +1046,7 @@ SLASHopt [/]*
                                        REJECT;
                                      }
                                    }
-<CComment,ReadLine,IncludeFile>{B}{B}{B}{B}[\\@]("snippet{"{B}*"doc"{B}*{OPTS}"}"|"snippetdoc") { // Markdown code section
+<CComment,ReadLine,IncludeFile>{B}{B}{B}{B}[\\@]("snippet"{OPTS}|"snippetdoc"{OPTS}*) { // Markdown code section
                                      if (Config_getBool(MARKDOWN_SUPPORT))
                                      {
 				       copyToOutput(yyscanner,yytext,yyleng);
@@ -1053,10 +1056,10 @@ SLASHopt [/]*
                                        REJECT;
                                      }
                                    }
-<CComment,ReadLine,IncludeFile>[\\@]("include{"{B}*"doc"{B}*{OPTS}"}"|"includedoc") {
+<CComment,ReadLine,IncludeFile>[\\@]("include"{OPTS}|"includedoc"{OPTS}*) {
+                                     if (!parseIncludeOptions(yyscanner,std::string_view{yytext,static_cast<size_t>(yyleng)})) REJECT;
                                      yyextra->includeCtx = YY_START;
                                      yyextra->firstIncludeLine = true;
-                                     parseIncludeOptions(yyscanner,std::string_view{yytext,static_cast<size_t>(yyleng)});
                                      if (!yyextra->insertCppCommentMarker && (yyextra->includeCtx==ReadLine || yyextra->includeCtx==IncludeFile))
                                      {
                                        if (yyextra->includeCtx==ReadLine)
@@ -1067,10 +1070,10 @@ SLASHopt [/]*
                                      }
                                      BEGIN(IncludeDoc);
                                    }
-<CComment,ReadLine,IncludeFile>[\\@]("snippet{"{B}*"doc"{B}*{OPTS}"}"|"snippetdoc") {
+<CComment,ReadLine,IncludeFile>[\\@]("snippet"{OPTS}|"snippetdoc"{OPTS}*) {
+                                     if (!parseIncludeOptions(yyscanner,std::string_view{yytext,static_cast<size_t>(yyleng)})) REJECT;
                                      yyextra->includeCtx = YY_START;
                                      yyextra->firstIncludeLine = true;
-                                     parseIncludeOptions(yyscanner,std::string_view{yytext,static_cast<size_t>(yyleng)});
                                      if (!yyextra->insertCppCommentMarker && (yyextra->includeCtx==ReadLine || yyextra->includeCtx==IncludeFile))
                                      {
                                        if (yyextra->includeCtx==ReadLine)
@@ -1285,9 +1288,14 @@ SLASHopt [/]*
                                        QCString lineStr= " \\ilinebr \\ifile \""+yyextra->fileName+"\" \\iline "+QCString().setNum(yyextra->lineNr)+" ";
                                        if (fs->oldRaiseLvl!=yyextra->raiseLevel)
                                        {
-                                          lineStr+=std::string(" \\iraise ") + std::to_string(fs->oldRaiseLvl);
+                                          lineStr+=" \\iraise " + std::to_string(fs->oldRaiseLvl);
+                                       }
+                                       if (fs->oldRaiseLbl!=yyextra->raiseLabel)
+                                       {
+                                          lineStr+=" \\iprefix \"" + fs->oldRaiseLbl + "\"";
                                        }
                                        yyextra->raiseLevel    = fs->oldRaiseLvl;
+                                       yyextra->raiseLabel    = fs->oldRaiseLbl;
                                        copyToOutput(yyscanner,lineStr.view());
                                        yyextra->includeStack.pop_back();
                                        //printf("<<EOF>> switch back to %s line %d inbufPos=%d outbufPos=%d\n",
@@ -1299,22 +1307,68 @@ SLASHopt [/]*
   */
 %%
 
-static void parseIncludeOptions(yyscan_t yyscanner,std::string_view s)
+static bool parseIncludeOptions(yyscan_t yyscanner,std::string_view s)
 {
   struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+
   //printf("parseIncludeOptions=%s\n",qPrint(QCString(s)));
-  static const reg::Ex re(R"(,\s*raise\s*=\s*(\d+))");
-  reg::Match match;
-  if (reg::search(s,match,re))
+  size_t optIdxStart = s.find('{');
+  size_t optIdxEnd   = optIdxStart!=std::string::npos ? s.find("}",optIdxStart+1) : std::string::npos;
+  std::string cmdName;
+  StringVector optList;
+  if (optIdxStart == std::string::npos) // no options
+  {
+    cmdName = stripWhiteSpace(s.substr(1)); // to remove {CMD}
+  }
+  else // options present
+  {
+    cmdName = stripWhiteSpace(s.substr(1,optIdxStart-1)); // to remove {CMD}
+    optList = split(std::string{s.substr(optIdxStart+1,optIdxEnd-optIdxStart-1)},",");
+  }
+  bool isDoc = cmdName=="includedoc" || cmdName=="snippetdoc";
+  for (const auto &opt : optList)
+  {
+    if (stripWhiteSpace(opt)==std::string_view{"doc"})
+    {
+      isDoc=true;
+      break;
+    }
+  }
+
+  if (isDoc)
   {
-    yyextra->raiseIncrement = atoi(match[1].str().c_str());
-    if (yyextra->raiseLevel+yyextra->raiseIncrement>=SectionType::MaxLevel) // check range
+    for (const auto &opt : optList)
     {
-      warn(yyextra->fileName,yyextra->lineNr,"Raising section level from %d to %d, exceeds allowed range [0-%d], adjusting",
-                yyextra->raiseLevel,yyextra->raiseLevel+yyextra->raiseIncrement,SectionType::MaxLevel-1);
-      yyextra->raiseIncrement = std::max(0,SectionType::MaxLevel-1-yyextra->raiseLevel);
+      std::string_view locOpt = stripWhiteSpace(opt);
+      size_t posEqual = locOpt.find('=');
+      std::string_view option = posEqual!=std::string::npos ? stripWhiteSpace(locOpt.substr(0,posEqual)) : locOpt;
+      std::string_view value  = posEqual!=std::string::npos ? stripWhiteSpace(locOpt.substr(posEqual+1)) : std::string_view();
+
+      if (option==std::string_view{"doc"} && value.empty())
+      {
+      }
+      else if (option==std::string_view{"raise"} && !value.empty())
+      {
+        yyextra->raiseIncrement = atoi(value.data());
+        if (yyextra->raiseLevel+yyextra->raiseIncrement>=SectionType::MaxLevel) // check range
+        {
+          warn(yyextra->fileName,yyextra->lineNr,"Raising section level from %d to %d, exceeds allowed range [0-%d], adjusting",
+              yyextra->raiseLevel,yyextra->raiseLevel+yyextra->raiseIncrement,SectionType::MaxLevel-1);
+          yyextra->raiseIncrement = std::max(0,SectionType::MaxLevel-1-yyextra->raiseLevel);
+        }
+      }
+      else if (option==std::string_view{"prefix"} && !value.empty())
+      {
+        yyextra->raisePrefix = value;
+      }
+      else
+      {
+        warn(yyextra->fileName,yyextra->lineNr,"Unsupported option '%s' for %s command",qPrint(option), qPrint(cmdName));
+      }
     }
   }
+
+  return isDoc;
 }
 
 
@@ -1633,12 +1687,18 @@ static bool readIncludeFile(yyscan_t yyscanner,const QCString &inc,const QCStrin
       }
     }
     int oldRaiseLevel = yyextra->raiseLevel;
+    QCString oldRaiseLabel = yyextra->raiseLabel;
     yyextra->raiseLevel+=yyextra->raiseIncrement;
+    yyextra->raiseLabel+=yyextra->raisePrefix;
     QCString lineStr=" \\ilinebr \\ifile \""+absFileName+"\" \\iline " + std::to_string(lineNr);
     if (yyextra->raiseLevel>0)
     {
       lineStr+=" \\iraise " + std::to_string(yyextra->raiseLevel);
     }
+    if (!yyextra->raiseLabel.isEmpty())
+    {
+      lineStr+=" \\iprefix \"" + yyextra->raiseLabel + "\"";
+    }
     lineStr+=" \\ilinebr ";
     copyToOutput(yyscanner,lineStr.view());
 
@@ -1651,6 +1711,7 @@ static bool readIncludeFile(yyscan_t yyscanner,const QCString &inc,const QCStrin
     fs->oldFileBufPos = yyextra->inBufPos;
     fs->oldIncludeCtx = yyextra->includeCtx;
     fs->oldRaiseLvl   = oldRaiseLevel;
+    fs->oldRaiseLbl   = oldRaiseLabel;
     fs->blockId       = blockId;
     yy_switch_to_buffer(yy_create_buffer(0, YY_BUF_SIZE, yyscanner),yyscanner);
     yyextra->fileName = absFileName;
@@ -1803,7 +1864,9 @@ void convertCppComments(const std::string &inBuf,std::string &outBuf,const std::
   yyextra->pythonDocString = FALSE;
   yyextra->lineNr   = 1;
   yyextra->raiseLevel = 0;
+  yyextra->raiseLabel = "";
   yyextra->raiseIncrement = 0;
+  yyextra->raisePrefix = "";
   yyextra->insertCppCommentMarker=false;
   yyextra->expandedAliases.clear();
   while (!yyextra->condStack.empty()) yyextra->condStack.pop();