More flexible group dependency graphs regarding show / hide

For call / caller / include / included by graphs it is possible to steer the graph creation process on a 1 to 1 base (commands like \callgraph and \hidecallgraph).

Introducing for the group dependency graphs:
```
    \groupgraph and \hidegroupgraph
```

Author: albert-github

doc/commands.doc

@@ -116,10 +116,12 @@ documentation:
 \refitem cmdfile \\file
 \refitem cmdfileinfo \\fileinfo
 \refitem cmdfn \\fn
+\refitem cmdgroupgraph \\groupgraph
 \refitem cmdheaderfile \\headerfile
 \refitem cmdhidecallergraph \\hidecallergraph
 \refitem cmdhidecallgraph \\hidecallgraph
 \refitem cmdhidedirectorygraph \\hidedirectorygraph
+\refitem cmdhidegroupgraph \\hidegroupgraph
 \refitem cmdhideincludedbygraph \\hideincludedbygraph
 \refitem cmdhideincludegraph \\hideincludegraph
 \refitem cmdhiderefby \\hiderefby
@@ -515,6 +517,32 @@ Structural indicators
   \sa section \ref cmddirectorygraph "\\directorygraph",
       option \ref cfg_directory_graph "DIRECTORY_GRAPH"
 
+<hr>
+\section cmdgroupgraph \\groupgraph
+
+  \addindex \\groupgraph
+  When this command is put in a comment block of a
+  \ref cmddefgroup "\\defgroup" command
+  then doxygen will generate a group dependency graph for that group. The
+  group graph will be generated regardless of the value of
+  \ref cfg_group_graphs "GROUP_GRAPHS".
+
+  \sa section \ref cmdhidegroupgraph "\\hidegroupgraph",
+      option \ref cfg_group_graphs "GROUP_GRAPHS"
+
+<hr>
+\section cmdhidegroupgraph \\hidegroupgraph
+
+  \addindex \\hidegroupgraph
+  When this command is put in a comment block of a
+  \ref cmddefgroup "\\defgroup" command
+  then doxygen will not generate a group dependency graph for that group. The
+  group graph will not be generated regardless of the value of
+  \ref cfg_group_graphs "GROUP_GRAPHS".
+
+  \sa section \ref cmdgroupgraph "\\groupgraph",
+      option \ref cfg_group_graphs "GROUP_GRAPHS"
+
 <hr>
 \section cmdqualifier \\qualifier <label> | "(text)"
 

src/commentscan.l

@@ -134,6 +134,8 @@ static bool handleReferencedByRelation(yyscan_t yyscanner,const QCString &, cons
 static bool handleHideReferencedByRelation(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleReferencesRelation(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleHideReferencesRelation(yyscan_t yyscanner,const QCString &, const StringVector &);
+static bool handleGroupgraph(yyscan_t yyscanner,const QCString &, const StringVector &);
+static bool handleHideGroupgraph(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleInternal(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleStatic(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handlePure(yyscan_t yyscanner,const QCString &, const StringVector &);
@@ -227,10 +229,12 @@ static const std::map< std::string, DocCmdMap > docCmdMap =
   { "extends",         { &handleExtends,          CommandSpacing::Invisible }},
   { "file",            { &handleFile,             CommandSpacing::Invisible }},
   { "fn",              { &handleFn,               CommandSpacing::Invisible }},
+  { "groupgraph",      { &handleGroupgraph,       CommandSpacing::Invisible }},
   { "headerfile",      { &handleHeaderFile,       CommandSpacing::Invisible }},
   { "hidecallergraph", { &handleHideCallergraph,  CommandSpacing::Invisible }},
   { "hidecallgraph",   { &handleHideCallgraph,    CommandSpacing::Invisible }},
   { "hidedirectorygraph",  { &handleHideDirectoryGraph,  CommandSpacing::Invisible }},
+  { "hidegroupgraph",  { &handleHideGroupgraph,  CommandSpacing::Invisible }},
   { "hideincludedbygraph", { &handleHideIncludedBygraph, CommandSpacing::Invisible }},
   { "hideincludegraph",    { &handleHideIncludegraph,    CommandSpacing::Invisible }},
   { "hideinitializer", { &handleHideInitializer,  CommandSpacing::Invisible }},
@@ -3123,6 +3127,20 @@ static bool handleHideDirectoryGraph(yyscan_t yyscanner,const QCString &, const
   return FALSE;
 }
 
+static bool handleGroupgraph(yyscan_t yyscanner,const QCString &, const StringVector &)
+{
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  yyextra->current->groupGraph = TRUE; // ON
+  return FALSE;
+}
+
+static bool handleHideGroupgraph(yyscan_t yyscanner,const QCString &, const StringVector &)
+{
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  yyextra->current->groupGraph = FALSE; // OFF
+  return FALSE;
+}
+
 static bool handleQualifier(yyscan_t yyscanner,const QCString &cmd, const StringVector &)
 {
   struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;

src/config.xml

@@ -3769,6 +3769,10 @@ where `loc1` and `loc2` can be relative or absolute paths or URLs.
 <![CDATA[
  If the \c GROUP_GRAPHS tag is set to \c YES then doxygen
  will generate a graph for groups, showing the direct groups dependencies.
+ Explicit enabling a group dependency graph, when \c GROUP_GRAPHS is set to \c NO, can be
+ accomplished by means of the command \ref cmdgroupgraph "\\groupgraph".
+ Disabling a directory graph can be accomplished by means of the command
+ \ref cmdhidegroupgraph "\\hidegroupgraph".
 
  See also the chapter \ref grouping "Grouping" in the manual.
 ]]>

src/dotgroupcollaboration.cpp

@@ -321,6 +321,16 @@ bool DotGroupCollaboration::isTrivial() const
   return m_usedNodes.size() <= 1;
 }
 
+bool DotGroupCollaboration::isTooBig() const
+{
+  return numNodes()>=Config_getInt(DOT_GRAPH_MAX_NODES);
+}
+
+int DotGroupCollaboration::numNodes() const
+{
+  return static_cast<int>(m_usedNodes.size());
+}
+
 void DotGroupCollaboration::writeGraphHeader(TextStream &t,const QCString &title) const
 {
   DotGraph::writeGraphHeader(t, title);

src/dotgroupcollaboration.h

@@ -34,6 +34,8 @@ class DotGroupCollaboration : public DotGraph
                         const QCString &path,const QCString &fileName,const QCString &relPath,
                         bool writeImageMap=TRUE,int graphId=-1);
     bool isTrivial() const;
+    bool isTooBig() const;
+    int numNodes() const;
 
   protected:
     virtual QCString getBaseName() const;

src/doxygen.cpp

@@ -368,6 +368,10 @@ static void buildGroupListFiltered(const Entry *root,bool additional, bool inclu
         gd->addSectionsToDefinition(root->anchors);
         gd->setRefItems(root->sli);
         gd->setLanguage(root->lang);
+        if (root->groupDocType==Entry::GROUPDOC_NORMAL)
+        {
+          gd->enableGroupGraph(root->groupGraph);
+        }
       }
       else
       {
@@ -391,6 +395,10 @@ static void buildGroupListFiltered(const Entry *root,bool additional, bool inclu
         gd->addSectionsToDefinition(root->anchors);
         gd->setRefItems(root->sli);
         gd->setLanguage(root->lang);
+        if (root->groupDocType==Entry::GROUPDOC_NORMAL)
+        {
+          gd->enableGroupGraph(root->groupGraph);
+        }
       }
     }
   }

src/entry.cpp

@@ -68,6 +68,7 @@ Entry::Entry(const Entry &e)
   includeGraph = e.includeGraph;
   includedByGraph = e.includedByGraph;
   directoryGraph = e.directoryGraph;
+  groupGraph  = e.groupGraph;
   referencedByRelation = e.referencedByRelation;
   referencesRelation   = e.referencesRelation;
   exported    = e.exported;
@@ -194,6 +195,7 @@ void Entry::reset()
   bool entryIncludeGraph    = Config_getBool(INCLUDE_GRAPH);
   bool entryIncludedByGraph = Config_getBool(INCLUDED_BY_GRAPH);
   bool entryDirectoryGraph  = Config_getBool(DIRECTORY_GRAPH);
+  bool entryGroupGraph  = Config_getBool(GROUP_GRAPHS);
   //printf("Entry::reset()\n");
   name.resize(0);
   type.resize(0);
@@ -229,6 +231,7 @@ void Entry::reset()
   includeGraph = entryIncludeGraph;
   includedByGraph = entryIncludedByGraph;
   directoryGraph = entryDirectoryGraph;
+  groupGraph = entryGroupGraph;
   referencedByRelation = entryReferencedByRelation;
   referencesRelation   = entryReferencesRelation;
   exported = false;

src/entry.h

@@ -259,6 +259,7 @@ class Entry
     bool includeGraph;        //!< do we need to draw the include graph?
     bool includedByGraph;     //!< do we need to draw the included by graph?
     bool directoryGraph;      //!< do we need to draw the directory graph?
+    bool groupGraph;          //!< do we need to draw the group graph?
     bool exported;            //!< is the symbol exported from a C++20 module
     Specifier    virt;        //!< virtualness of the entry
     QCString     args;        //!< member argument string

src/groupdef.cpp

@@ -119,6 +119,8 @@ class GroupDefImpl : public DefinitionMixin<GroupDef>
     virtual void sortSubGroups() override;
     virtual void writeSummaryLinks(OutputList &ol) const override;
 
+    virtual bool hasGroupGraph() const override;
+    virtual void enableGroupGraph(bool e) override;
   private:
     void addMemberListToGroup(MemberList *,bool (MemberDef::*)() const);
     void addMemberToList(MemberListType lt,MemberDef *md);
@@ -164,6 +166,7 @@ class GroupDefImpl : public DefinitionMixin<GroupDef>
     MemberLists          m_memberLists;
     MemberGroupList      m_memberGroups;
     bool                 m_subGrouping;
+    bool                 m_hasGroupGraph = false;
 
 };
 
@@ -193,6 +196,7 @@ GroupDefImpl::GroupDefImpl(const QCString &df,int dl,const QCString &na,const QC
   //visited = 0;
   m_groupScope = 0;
   m_subGrouping=Config_getBool(SUBGROUPING);
+  m_hasGroupGraph=Config_getBool(GROUP_GRAPHS);
 }
 
 GroupDefImpl::~GroupDefImpl()
@@ -873,10 +877,15 @@ void GroupDefImpl::writeBriefDescription(OutputList &ol)
 
 void GroupDefImpl::writeGroupGraph(OutputList &ol)
 {
-  if (Config_getBool(HAVE_DOT) /*&& Config_getBool(GROUP_GRAPHS)*/ )
+  if (Config_getBool(HAVE_DOT) && m_hasGroupGraph /*&& Config_getBool(GROUP_GRAPHS)*/)
   {
     DotGroupCollaboration graph(this);
-    if (!graph.isTrivial())
+    if (graph.isTooBig())
+    {
+       warn_uncond("Group dependency graph for '%s' not generated, too many nodes (%d), threshold is %d. Consider increasing DOT_GRAPH_MAX_NODES.\n",
+           qPrint(name()), graph.numNodes(), Config_getInt(DOT_GRAPH_MAX_NODES));
+    }
+    else if (!graph.isTrivial())
     {
       msg("Generating dependency graph for group %s\n",qPrint(qualifiedName()));
       ol.pushGeneratorState();
@@ -1882,6 +1891,16 @@ bool GroupDefImpl::hasDetailedDescription() const
          (m_pages.size()!=numDocMembers());
 }
 
+void GroupDefImpl::enableGroupGraph(bool e)
+{
+  m_hasGroupGraph=e;
+}
+
+bool GroupDefImpl::hasGroupGraph() const
+{
+  return m_hasGroupGraph;
+}
+
 // --- Cast functions
 
 GroupDef *toGroupDef(Definition *d)

src/groupdef.h

@@ -112,6 +112,9 @@ class GroupDef : public DefinitionMutable, public Definition
     virtual bool hasDetailedDescription() const = 0;
     virtual void sortSubGroups() = 0;
 
+    // group graph related members
+    virtual bool hasGroupGraph() const = 0;
+    virtual void enableGroupGraph(bool e) = 0;
 };
 
 std::unique_ptr<GroupDef> createGroupDef(const QCString &fileName,int line,const QCString &name,

templates/general/layout_default.xml

@@ -184,7 +184,7 @@
   <!-- Layout definition for a group page -->
   <group>
     <briefdescription visible="yes"/>
-    <groupgraph visible="$GROUP_GRAPHS"/>
+    <groupgraph visible="yes"/>
     <memberdecl>
       <nestedgroups visible="yes" title=""/>
       <modules visible="yes" title=""/>