issue #8256 Possible to get enum values in the Enumeration Type documentation

Instead of steering the showing of the enum values by mean is the `MAX_INIT_LINES` it is now, more flexible,  steered by the setting `SHOW_ENUM_VALUES` and the commands `\showenumvalues` and `\hideenumvalues`.

Author: albert-github

doc/commands.doc

@@ -123,6 +123,7 @@ documentation:
 \refitem cmdhidecallgraph \\hidecallgraph
 \refitem cmdhidecollaborationgraph \\hidecollaborationgraph
 \refitem cmdhidedirectorygraph \\hidedirectorygraph
+\refitem cmdhideenumvalues \\hideenumvalues
 \refitem cmdhidegroupgraph \\hidegroupgraph
 \refitem cmdhideincludedbygraph \\hideincludedbygraph
 \refitem cmdhideincludegraph \\hideincludegraph
@@ -208,6 +209,7 @@ documentation:
 \refitem cmdsee \\see
 \refitem cmdshort \\short
 \refitem cmdshowdate \\showdate
+\refitem cmdshowenumvalues \\showenumvalues
 \refitem cmdshowinitializer \\showinitializer
 \refitem cmdshowinlinesource \\showinlinesource
 \refitem cmdshowrefby \\showrefby
@@ -625,6 +627,28 @@ Structural indicators
   \sa section \ref cmdgroupgraph "\\groupgraph",
       option \ref cfg_group_graphs "GROUP_GRAPHS"
 
+<hr>
+\section cmdshowenumvalues \\showenumvalues
+
+  \addindex \\showenumvalues
+  When this command is put in a comment block of an enum
+  then doxygen will show the specified enum values for that enum,
+  regardless of the value of \ref cfg_show_enum_values "SHOW_ENUM_VALUES".
+
+  \sa section \ref cmdhideenumvalues "\\hideenumvalues",
+      option \ref cfg_show_enum_values "SHOW_ENUM_VALUES"
+
+<hr>
+\section cmdhideenumvalues \\hideenumvalues
+
+  \addindex \\hideenumvalues
+  When this command is put in a comment block of an enum
+  then doxygen will not show the specified enum values for that enum,
+  regardless of the value of \ref cfg_show_enum_values "SHOW_ENUM_VALUES".
+
+  \sa section \ref cmdshowenumvalues "\\showenumvalues",
+      option \ref cfg_show_enum_values "SHOW_ENUM_VALUES"
+
 <hr>
 \section cmdqualifier \\qualifier <label> | "(text)"
 

src/commentscan.l

@@ -126,6 +126,8 @@ static bool handleCallergraph(yyscan_t yyscanner,const QCString &, const StringV
 static bool handleHideCallergraph(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleIncludegraph(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleIncludedBygraph(yyscan_t yyscanner,const QCString &, const StringVector &);
+static bool handleShowEnumValues(yyscan_t yyscanner,const QCString &, const StringVector &);
+static bool handleHideEnumValues(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleShowInlineSource(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleHideInlineSource(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleHideIncludegraph(yyscan_t yyscanner,const QCString &, const StringVector &);
@@ -242,6 +244,7 @@ static const std::map< std::string, DocCmdMap > docCmdMap =
   { "hidecallgraph",   { &handleHideCallgraph,    CommandSpacing::Invisible }},
   { "hidecollaborationgraph", { &handleHideCollaborationgraph, CommandSpacing::Invisible }},
   { "hidedirectorygraph",  { &handleHideDirectoryGraph,  CommandSpacing::Invisible }},
+  { "hideenumvalues",  { &handleHideEnumValues,  CommandSpacing::Invisible }},
   { "hidegroupgraph",  { &handleHideGroupgraph,  CommandSpacing::Invisible }},
   { "hideincludedbygraph", { &handleHideIncludedBygraph, CommandSpacing::Invisible }},
   { "hideincludegraph",    { &handleHideIncludegraph,    CommandSpacing::Invisible }},
@@ -319,6 +322,7 @@ static const std::map< std::string, DocCmdMap > docCmdMap =
   { "section",         { &handleSection,          CommandSpacing::Block     }},
   { "see",             { 0,                       CommandSpacing::Block     }},
   { "short",           { &handleBrief,            CommandSpacing::Invisible }},
+  { "showenumvalues",  { &handleShowEnumValues,   CommandSpacing::Invisible }},
   { "showinitializer", { &handleShowInitializer,  CommandSpacing::Invisible }},
   { "showinlinesource",{ &handleShowInlineSource, CommandSpacing::Invisible }},
   { "showrefby",       { &handleReferencedByRelation,     CommandSpacing::Invisible }},
@@ -3101,6 +3105,20 @@ static bool handleHideCallergraph(yyscan_t yyscanner,const QCString &, const Str
   return FALSE;
 }
 
+static bool handleShowEnumValues(yyscan_t yyscanner,const QCString &, const StringVector &)
+{
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  yyextra->current->enumValues = TRUE; // ON
+  return FALSE;
+}
+
+static bool handleHideEnumValues(yyscan_t yyscanner,const QCString &, const StringVector &)
+{
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  yyextra->current->enumValues = FALSE; // OFF
+  return FALSE;
+}
+
 static bool handleShowInlineSource(yyscan_t yyscanner,const QCString &, const StringVector &)
 {
   struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;

src/config.xml

@@ -2604,6 +2604,14 @@ The \c DOCSET_PUBLISHER_NAME tag identifies the documentation publisher.
  that doxygen will group on one line in the generated HTML documentation.
  <br>Note that a value of 0 will completely suppress the enum values from
  appearing in the overview section.
+]]>
+      </docs>
+    </option>
+    <option type='bool' id='SHOW_ENUM_VALUES' defval='0'>
+      <docs>
+<![CDATA[
+ When the \c SHOW_ENUM_VALUES tag is set doxygen will show the specified enumeration values
+ besides the enumeration mnemonics.
 ]]>
       </docs>
     </option>

src/doxygen.cpp

@@ -7089,6 +7089,7 @@ static void findEnums(const Entry *root)
       mmd->enableReferencesRelation(root->referencesRelation);
       mmd->enableInlineSource(root->inlineSource);
       mmd->addQualifiers(root->qualifiers);
+      mmd->enableEnumValues(root->enumValues);
       //printf("%s::setRefItems(%zu)\n",qPrint(md->name()),root->sli.size());
       mmd->setRefItems(root->sli);
       //printf("found enum %s nd=%p\n",qPrint(md->name()),nd);

src/entry.cpp

@@ -73,6 +73,7 @@ Entry::Entry(const Entry &e) : section(e.section)
   referencedByRelation = e.referencedByRelation;
   referencesRelation   = e.referencesRelation;
   inlineSource = e.inlineSource;
+  enumValues  = e.enumValues;
   exported    = e.exported;
   virt        = e.virt;
   args        = e.args;
@@ -201,6 +202,7 @@ void Entry::reset()
   bool entryCollaborationGraph = Config_getBool(COLLABORATION_GRAPH);
   CLASS_GRAPH_t entryInheritanceGraph  = Config_getBool(CLASS_GRAPH);
   bool entryGroupGraph  = Config_getBool(GROUP_GRAPHS);
+  bool entryEnumValues  = Config_getBool(SHOW_ENUM_VALUES);
   //printf("Entry::reset()\n");
   name.resize(0);
   type.resize(0);
@@ -242,6 +244,7 @@ void Entry::reset()
   referencedByRelation = entryReferencedByRelation;
   referencesRelation   = entryReferencesRelation;
   inlineSource = entryInlineSource;
+  enumValues = entryEnumValues;
   exported = false;
   section = EntryType::makeEmpty();
   mtype   = MethodTypes::Method;

src/entry.h

@@ -198,6 +198,7 @@ class Entry
     bool includedByGraph;     //!< do we need to draw the included by graph?
     bool directoryGraph;      //!< do we need to draw the directory graph?
     bool collaborationGraph;  //!< do we need to draw the collaboration graph?
+    bool enumValues;          //!< do we need to show the enum values besides the mnemonics?
     CLASS_GRAPH_t inheritanceGraph; //!< type of inheritance graph?
     bool groupGraph;          //!< do we need to draw the group graph?
     bool exported;            //!< is the symbol exported from a C++20 module

src/memberdef.cpp

@@ -220,6 +220,7 @@ class MemberDefImpl : public DefinitionMixin<MemberDefMutable>
     virtual bool hasReferencesRelation() const override;
     virtual bool hasReferencedByRelation() const override;
     virtual bool hasInlineSource() const override;
+    virtual bool hasEnumValues() const override;
     virtual const MemberDef *templateMaster() const override;
     virtual QCString getScopeString() const override;
     virtual ClassDef *getClassDefOfAnonymousType() const override;
@@ -303,6 +304,7 @@ class MemberDefImpl : public DefinitionMixin<MemberDefMutable>
     virtual void mergeEnableReferencesRelation(bool other) override;
     virtual void enableInlineSource(bool e) override;
     virtual void mergeEnableInlineSource(bool other) override;
+    virtual void enableEnumValues(bool e) override;
     virtual void setTemplateMaster(MemberDef *mt) override;
     virtual void addListReference(Definition *d) override;
     virtual void setDocsForDefinition(bool b) override;
@@ -494,6 +496,7 @@ class MemberDefImpl : public DefinitionMixin<MemberDefMutable>
     bool m_hasReferencedByRelation = false;
     bool m_hasReferencesRelation = false;
     bool m_hasInlineSource = false;
+    bool m_hasEnumValues = false;
     bool m_explExt = false;             // member was explicitly declared external
     bool m_tspec = false;               // member is a template specialization
     bool m_groupHasDocs = false;        // true if the entry that caused the grouping was documented
@@ -855,6 +858,8 @@ class MemberDefAliasImpl : public DefinitionAliasMixin<MemberDef>
     { return getMdAlias()->hasReferencedByRelation(); }
     virtual bool hasInlineSource() const
     { return getMdAlias()->hasInlineSource(); }
+    virtual bool hasEnumValues() const
+    { return getMdAlias()->hasEnumValues(); }
     virtual StringVector getQualifiers() const
     { return getMdAlias()->getQualifiers(); }
     virtual const MemberDef *templateMaster() const
@@ -1331,6 +1336,7 @@ void MemberDefImpl::init(Definition *d,
   m_hasReferencedByRelation = FALSE;
   m_hasReferencesRelation = FALSE;
   m_hasInlineSource = FALSE;
+  m_hasEnumValues = FALSE;
   m_initLines=0;
   m_type=t;
   if (mt==MemberType_Typedef) m_type.stripPrefix("typedef ");
@@ -1508,6 +1514,7 @@ MemberDefImpl::MemberDefImpl(const MemberDefImpl &md) : DefinitionMixin(md)
   m_hasReferencedByRelation        = md.m_hasReferencedByRelation        ;
   m_hasReferencesRelation          = md.m_hasReferencesRelation          ;
   m_hasInlineSource                = md.m_hasInlineSource                ;
+  m_hasEnumValues                  = md.m_hasEnumValues                  ;
   m_explExt                        = md.m_explExt                        ;
   m_tspec                          = md.m_tspec                          ;
   m_groupHasDocs                   = md.m_groupHasDocs                   ;
@@ -3179,14 +3186,17 @@ void MemberDefImpl::_writeEnumValues(OutputList &ol,const Definition *container,
     bool first=true;
     //printf("** %s: enum values=%zu\n",qPrint(name()),enumFieldList().size());
     bool hasInits = false;
-    for (const auto &fmd : enumFieldList())
+    if (hasEnumValues())
     {
-      if (fmd->isLinkable())
+      for (const auto &fmd : enumFieldList())
       {
-        if (!fmd->initializer().isEmpty())
+        if (fmd->isLinkable())
         {
-          hasInits = true;
-          break;
+          if (!fmd->initializer().isEmpty())
+          {
+            hasInits = true;
+            break;
+          }
         }
       }
     }
@@ -4934,6 +4944,11 @@ void MemberDefImpl::mergeEnableInlineSource(bool other)
   }
 }
 
+void MemberDefImpl::enableEnumValues(bool e)
+{
+  m_hasEnumValues=e;
+}
+
 bool MemberDefImpl::isObjCMethod() const
 {
   if (getClassDef() && getClassDef()->isObjectiveC() && isFunction()) return TRUE;
@@ -5676,6 +5691,11 @@ bool MemberDefImpl::hasInlineSource() const
   return m_hasInlineSource;
 }
 
+bool MemberDefImpl::hasEnumValues() const
+{
+  return m_hasEnumValues;
+}
+
 const MemberDef *MemberDefImpl::templateMaster() const
 {
   return m_templateMaster;

src/memberdef.h

@@ -245,6 +245,7 @@ class MemberDef : public Definition
     virtual bool hasReferencedByRelation() const = 0;
 
     virtual bool hasInlineSource() const = 0;
+    virtual bool hasEnumValues() const = 0;
 
     virtual const MemberDef *templateMaster() const = 0;
     virtual QCString getScopeString() const = 0;
@@ -394,6 +395,8 @@ class MemberDefMutable : public DefinitionMutable, public MemberDef
     virtual void enableInlineSource(bool e) = 0;
     virtual void mergeEnableInlineSource(bool other) = 0;
 
+    virtual void enableEnumValues(bool e) = 0;
+
     virtual void setTemplateMaster(MemberDef *mt) = 0;
     virtual void addListReference(Definition *d) = 0;
     virtual void setDocsForDefinition(bool b) = 0;