issue #11245 Add class attribute to the @qualifier command in the H…

…TML output Adding the possibility to have (HTML) class attribute values as options with the `@qualifier` command.
doxygen · albert-github · Nov 23, 2024 · Nov 23, 2024 · Nov 23, 2024 · 41efed326e945f067fc80330b050b60df1bb00bf
commit 41efed326e945f067fc80330b050b60df1bb00bf
diff --git a/doc/commands.dox b/doc/commands.dox
@@ -654,14 +654,16 @@ Structural indicators
       option \ref cfg_show_enum_values "SHOW_ENUM_VALUES"
 
 <hr>
-\section cmdqualifier \\qualifier \<label\> | "(text)"
+\section cmdqualifier \\qualifier['{'[option][,option]*'}'] \<label\> | "(text)"
 
   \addindex \\qualifier
 
   With this command it is possible to add custom qualifier labels
   to members and classes. These labels will be shown in the output in the same way
   as the automatically generated labels such as "static", "inline", and "final".
 
+  The `option` is the name to be appended of the HTML class atribute for the qualifier.
+
   For instance to indicate that a function is only meant for testing purposes
   one could add `\qualifier test`
 

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
@@ -302,6 +302,7 @@ add_library(doxymain STATIC
     plantuml.cpp
     qcstring.cpp
     qhp.cpp
+    qualifiers.cpp
     reflist.cpp
     regex.cpp
     resourcemgr.cpp

diff --git a/src/classdef.cpp b/src/classdef.cpp
@@ -271,7 +271,7 @@ class ClassDefImpl : public DefinitionMixin<ClassDefMutable>
     bool isSliceLocal() const override;
     bool hasNonReferenceSuperClass() const override;
     QCString requiresClause() const override;
-    StringVector getQualifiers() const override;
+    QualifierInfoVector getQualifiers() const override;
     bool containsOverload(const MemberDef *md) const override;
     ClassDef *insertTemplateInstance(const QCString &fileName,int startLine,int startColumn,
                                 const QCString &templSpec,bool &freshInstance) const override;
@@ -297,7 +297,7 @@ class ClassDefImpl : public DefinitionMixin<ClassDefMutable>
     void setCompoundType(CompoundType t) override;
     void setClassName(const QCString &name) override;
     void setClassSpecifier(TypeSpecifier spec) override;
-    void addQualifiers(const StringVector &qualifiers) override;
+    void addQualifiers(const QualifierInfoVector &qualifiers) override;
     void setTemplateArguments(const ArgumentList &al) override;
     void setTemplateBaseClassNames(const TemplateNameMap &templateNames) override;
     void setTemplateMaster(const ClassDef *tm) override;
@@ -586,7 +586,7 @@ class ClassDefAliasImpl : public DefinitionAliasMixin<ClassDef>
     { return getCdAlias()->hasNonReferenceSuperClass(); }
     QCString requiresClause() const override
     { return getCdAlias()->requiresClause(); }
-    StringVector getQualifiers() const override
+    QualifierInfoVector getQualifiers() const override
     { return getCdAlias()->getQualifiers(); }
     bool containsOverload(const MemberDef *md) const override
     { return getCdAlias()->containsOverload(md); }
@@ -800,7 +800,7 @@ class ClassDefImpl::IMPL
     /** C++20 requires clause */
     QCString requiresClause;
 
-    StringVector qualifiers;
+    QualifierInfoVector qualifiers;
 
     bool hasCollaborationGraph = false;
     CLASS_GRAPH_t typeInheritanceGraph = CLASS_GRAPH_t::NO;
@@ -2702,32 +2702,25 @@ void ClassDefImpl::writeDeclarationLink(OutputList &ol,bool &found,const QCStrin
 
 void ClassDefImpl::addClassAttributes(OutputList &ol) const
 {
-  StringVector sl;
-  if (isFinal())    sl.emplace_back("final");
-  if (isSealed())   sl.emplace_back("sealed");
-  if (isAbstract()) sl.emplace_back("abstract");
-  if (isExported()) sl.emplace_back("export");
-  if (getLanguage()==SrcLangExt::IDL && isPublished()) sl.emplace_back("published");
+  QualifierInfoVector slm;
+  if (isFinal())    insertQualifier(slm,"final");
+  if (isSealed())   insertQualifier(slm,"sealed");
+  if (isAbstract()) insertQualifier(slm,"abstract");
+  if (isExported()) insertQualifier(slm,"export");
+  if (getLanguage()==SrcLangExt::IDL && isPublished()) insertQualifier(slm,"published");
 
-  for (const auto &sx : m_impl->qualifiers)
-  {
-    bool alreadyAdded = std::find(sl.begin(), sl.end(), sx) != sl.end();
-    if (!alreadyAdded)
-    {
-      sl.push_back(sx);
-    }
-  }
+  mergeQualifier(slm, m_impl->qualifiers);
 
   ol.pushGeneratorState();
   ol.disableAllBut(OutputType::Html);
-  if (!sl.empty())
+  if (!slm.empty())
   {
     ol.startLabels();
     size_t i=0;
-    for (const auto &s : sl)
+    for (const auto &qi : slm)
     {
       i++;
-      ol.writeLabel(s.c_str(),i==sl.size());
+      ol.writeLabel(qi->label.c_str(),qi->classes,i==slm.size());
     }
     ol.endLabels();
   }
@@ -5176,19 +5169,12 @@ void ClassDefImpl::setClassSpecifier(TypeSpecifier spec)
   m_impl->spec = spec;
 }
 
-void ClassDefImpl::addQualifiers(const StringVector &qualifiers)
+void ClassDefImpl::addQualifiers(const QualifierInfoVector &qualifiers)
 {
-  for (const auto &sx : qualifiers)
-  {
-    bool alreadyAdded = std::find(m_impl->qualifiers.begin(), m_impl->qualifiers.end(), sx) != m_impl->qualifiers.end();
-    if (!alreadyAdded)
-    {
-      m_impl->qualifiers.push_back(sx);
-    }
-  }
+  mergeQualifier(m_impl->qualifiers,qualifiers);
 }
 
-StringVector ClassDefImpl::getQualifiers() const
+QualifierInfoVector ClassDefImpl::getQualifiers() const
 {
   r
A92E
eturn m_impl->qualifiers;
 }

diff --git a/src/classdef.h b/src/classdef.h
@@ -21,6 +21,7 @@
 #include <unordered_set>
 
 #include "containers.h"
+#include "qualifiers.h"
 #include "definition.h"
 #include "arguments.h"
 #include "membergroup.h"
@@ -328,7 +329,7 @@ class ClassDef : public Definition
     virtual bool hasNonReferenceSuperClass() const = 0;
 
     virtual QCString requiresClause() const = 0;
-    virtual StringVector getQualifiers() const = 0;
+    virtual QualifierInfoVector getQualifiers() const = 0;
 
     virtual bool containsOverload(const MemberDef *md) const = 0;
 
@@ -403,7 +404,7 @@ class ClassDefMutable : public DefinitionMutable, public ClassDef
     virtual void setTagLessReference(const ClassDef *cd) = 0;
     virtual void setMetaData(const QCString &md) = 0;
     virtual void setRequiresClause(const QCString &req) = 0;
-    virtual void addQualifiers(const StringVector &qualifiers) = 0;
+    virtual void addQualifiers(const QualifierInfoVector &qualifiers) = 0;
         // inheritance graph related members
     virtual CLASS_GRAPH_t hasInheritanceGraph() const = 0;
     virtual void overrideInheritanceGraph(CLASS_GRAPH_t e) = 0;

diff --git a/src/commentscan.l b/src/commentscan.l
@@ -66,6 +66,7 @@ typedef yyguts_t *yyscan_t;
 #include "trace.h"
 #include "debug.h"
 #include "stringutil.h"
+#include "qualifiers.h"
 
 // forward declarations
 static bool handleBrief(yyscan_t yyscanner,const QCString &, const StringVector &);
@@ -520,9 +521,9 @@ struct commentscanYY_state
   QCString         htmlAnchorStr;
   bool             htmlAnchor = false;
   bool             CScode = false;
+  StringVector     qualifierClasses;
 };
 
-
 static std::mutex g_sectionMutex;
 static std::mutex g_formulaMutex;
 static std::mutex g_citeMutex;
@@ -1744,12 +1745,12 @@ STopt  [^\n@\\]*
 
   /* ----- handle arguments of the qualifier command ----- */
 <Qualifier>{LABELID}                    { // unquoted version, simple label
-                                          yyextra->current->qualifiers.emplace_back(yytext);
+                                          mergeQualifier(yyextra->current->qualifiers, yytext, yyextra->qualifierClasses);
                                           BEGIN( Comment );
                                         }
 <Qualifier>"\""[^\"]*"\""               { // quotes version, add without quotes
-                                          std::string inp(yytext);
-                                          yyextra->current->qualifiers.push_back(inp.substr(1,yyleng-2));
+                                          std::string inp = std::string(yytext).substr(1,yyleng-2);
+                                          mergeQualifier(yyextra->current->qualifiers, inp, yyextra->qualifierClasses);
                                           BEGIN( Comment );
                                         }
 <Qualifier>{DOCNL}                      { // missing argument
@@ -3896,10 +3897,30 @@ static bool handleHideReferencesRelation(yyscan_t yyscanner,const QCString &, co
   return FALSE;
 }
 
-static bool handleQualifier(yyscan_t yyscanner,const QCString &cmd, const StringVector &)
+static bool handleQualifier(yyscan_t yyscanner,const QCString &cmd, const StringVector &optList)
 {
+  static const reg::Ex className(R"([a-zA-Z][a-zA-Z0-9_-]*)");
   struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
   yyextra->currentCmd = cmd;
+  yyextra->qualifierClasses.clear();
+  for (const auto &opt_ : optList)
+  {
+    std::string opt = QCString(opt_).stripWhiteSpace().str();
+    reg::Match match;
+    if (opt.empty())
+    {
+      continue;
+    }
+    else if (!reg::match(opt,match,className))
+    {
+      warn(yyextra->fileName,yyextra->lineNr,"Option '%s' contains non supported character with '\\%s' command", qPrint(opt),qPrint(cmd));
+    }
+    else if (std::find(yyextra->qualifierClasses.begin(), yyextra->qualifierClasses.end(), opt) == yyextra->qualifierClasses.end())
+    {
+      yyextra->qualifierClasses.push_back(opt);
+    }
+    opt = "";
+  }
   BEGIN(Qualifier);
   return FALSE;
 }

diff --git a/src/conceptdef.cpp b/src/conceptdef.cpp
@@ -504,7 +504,7 @@ void ConceptDefImpl::addConceptAttributes(OutputList &ol) const
     ol.pushGeneratorState();
     ol.disableAllBut(OutputType::Html);
     ol.startLabels();
-    ol.writeLabel("export",false);
+    ol.writeLabel("export",StringVector{"export"},false);
     ol.endLabels();
     ol.popGeneratorState();
   }

diff --git a/src/docbookgen.cpp b/src/docbookgen.cpp
@@ -1013,7 +1013,7 @@ void  DocbookGenerator::startLabels()
 DB_GEN_C
 }
 
-void  DocbookGenerator::writeLabel(const QCString &l,bool isLast)
+void  DocbookGenerator::writeLabel(const QCString &l,const StringVector &,bool isLast)
 {
 DB_GEN_C
   m_t << "<computeroutput>[" << l << "]</computeroutput>";

diff --git a/src/docbookgen.h b/src/docbookgen.h
@@ -308,7 +308,7 @@ class DocbookGenerator : public OutputGenerator, public OutputGenIntf
     void endInlineMemberDoc() override;
 
     void startLabels() override;
-    void writeLabel(const QCString &,bool) override;
+    void writeLabel(const QCString &,const StringVector &,bool) override;
     void endLabels() override;
 
     void writeLocalToc(const SectionRefs &sr,const LocalToc &lt) override;

diff --git a/src/entry.h b/src/entry.h
@@ -28,6 +28,7 @@
 #include "reflist.h"
 #include "textstream.h"
 #include "configvalues.h"
+#include "qualifiers.h"
 
 class SectionInfo;
 class FileDef;
@@ -232,7 +233,7 @@ class Entry
     LocalToc    localToc;
     QCString    metaData;     //!< Slice metadata
     QCString    req;          //!< C++20 requires clause
-    std::vector<std::string> qualifiers;  //!< qualifiers specified with the qualifier command
+    QualifierInfoVector qualifiers;  //!< qualifiers specified with the qualifier command
 
     /// return the command name used to define GROUPDOC_SEC
     const char *groupDocCmd() const

diff --git a/src/htmlgen.cpp b/src/htmlgen.cpp
@@ -3420,12 +3420,17 @@ void HtmlGenerator::startLabels()
   m_t << "<span class=\"mlabels\">";
 }
 
-void HtmlGenerator::writeLabel(const QCString &l,bool /*isLast*/)
+void HtmlGenerator::writeLabel(const QCString &l,const StringVector &cls,bool /*isLast*/)
 {
   DBG_HTML(m_t << "<!-- writeLabel(" << l << ") -->\n";)
   //m_t << "<tt>[" << l << "]</tt>";
   //if (!isLast) m_t << ", ";
-  m_t << "<span class=\"mlabel\">" << l << "</span>";
+  m_t << "<span class=\"mlabel";
+  for (auto & elem : cls)
+  {
+    m_t << " " << elem;
+  }
+  m_t << "\">" << l << "</span>";
 }
 
 void HtmlGenerator::endLabels()

diff --git a/src/htmlgen.h b/src/htmlgen.h
@@ -321,7 +321,7 @@ class HtmlGenerator : public OutputGenerator, public OutputGenIntf
     void endInlineMemberDoc() override;
 
     void startLabels() override;
-    void writeLabel(const QCString &l,bool isLast) override;
+    void writeLabel(const QCString &l,const StringVector &cls,bool isLast) override;
     void endLabels() override;
 
     void writeLocalToc(const SectionRefs &sr,const LocalToc &lt) override;

diff --git a/src/latexgen.cpp b/src/latexgen.cpp
@@ -2280,7 +2280,7 @@ void LatexGenerator::startLabels()
   m_t << "\\hspace{0.3cm}";
 }
 
-void LatexGenerator::writeLabel(const QCString &l,bool isLast)
+void LatexGenerator::writeLabel(const QCString &l,const StringVector &,bool isLast)
 {
   m_t << "{\\ttfamily [" << l << "]}";
   if (!isLast) m_t << ", ";

diff --git a/src/latexgen.h b/src/latexgen.h
@@ -307,7 +307,7 @@ class LatexGenerator : public OutputGenerator, public OutputGenIntf
     void endInlineMemberDoc() override;
 
     void startLabels() override;
-    void writeLabel(const QCString &l,bool isLast) override;
+    void writeLabel(const QCString &l,const StringVector &cls,bool isLast) override;
     void endLabels() override;
 
     void writeLocalToc(const SectionRefs &sr,const LocalToc &lt) override;

diff --git a/src/mangen.cpp b/src/mangen.cpp
@@ -900,7 +900,7 @@ void ManGenerator::startLabels()
 {
 }
 
-void ManGenerator::writeLabel(const QCString &l,bool isLast)
+void ManGenerator::writeLabel(const QCString &l,const StringVector &,bool isLast)
 {
   m_t << "\\fR [" << l << "]\\fP";
   if (!isLast) m_t << ", ";

diff --git a/src/mangen.h b/src/mangen.h
@@ -277,7 +277,7 @@ class ManGenerator : public OutputGenerator, public OutputGenIntf
     void endInlineMemberDoc() override;
 
     void startLabels() override;
-    void writeLabel(const QCString &l,bool isLast) override;
+    void writeLabel(const QCString &l,const StringVector &cls,bool isLast) override;
     void endLabels() override;
 
     void writeLocalToc(const SectionRefs &,const LocalToc &) override {}