From e5e0d795f84b7e4fe28f1a46532775a4124b6129 Mon Sep 17 00:00:00 2001
From: albert-github <albert.tests@gmail.com>
Date: Wed, 23 Aug 2023 11:52:04 +0200
Subject: [PATCH] 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
```
---
 doc/commands.doc                     | 28 ++++++++++++++++++++++++++++
 src/commentscan.l                    | 18 ++++++++++++++++++
 src/config.xml                       |  4 ++++
 src/dotgroupcollaboration.cpp        | 10 ++++++++++
 src/dotgroupcollaboration.h          |  2 ++
 src/doxygen.cpp                      |  8 ++++++++
 src/entry.cpp                        |  3 +++
 src/entry.h                          |  1 +
 src/groupdef.cpp                     | 23 +++++++++++++++++++++--
 src/groupdef.h                       |  3 +++
 templates/general/layout_default.xml |  2 +-
 11 files changed, 99 insertions(+), 3 deletions(-)

diff --git a/doc/commands.doc b/doc/commands.doc
index 564edcb5311..d5772210ebf 100644
--- a/doc/commands.doc
+++ b/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)"
 
diff --git a/src/commentscan.l b/src/commentscan.l
index 2407c642214..a253e56c3b5 100644
--- a/src/commentscan.l
+++ b/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;
diff --git a/src/config.xml b/src/config.xml
index d61dab61a41..a0e02fb9146 100644
--- a/src/config.xml
+++ b/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.
 ]]>
diff --git a/src/dotgroupcollaboration.cpp b/src/dotgroupcollaboration.cpp
index d5eb4093136..fe5f51cea4e 100644
--- a/src/dotgroupcollaboration.cpp
+++ b/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);
diff --git a/src/dotgroupcollaboration.h b/src/dotgroupcollaboration.h
index ddb12bb7a9a..f3b61c70d81 100644
--- a/src/dotgroupcollaboration.h
+++ b/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;
diff --git a/src/doxygen.cpp b/src/doxygen.cpp
index a344c52aaa7..bed4f9bde00 100644
--- a/src/doxygen.cpp
+++ b/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);
+        }
       }
     }
   }
diff --git a/src/entry.cpp b/src/entry.cpp
index 726df435db5..e6590e7f9c4 100644
--- a/src/entry.cpp
+++ b/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;
diff --git a/src/entry.h b/src/entry.h
index 78bd469dfc0..a592396535c 100644
--- a/src/entry.h
+++ b/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
diff --git a/src/groupdef.cpp b/src/groupdef.cpp
index 06eb56fe994..32d9de41aa6 100644
--- a/src/groupdef.cpp
+++ b/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)
diff --git a/src/groupdef.h b/src/groupdef.h
index 912c19f4cd0..1817ed9d2e6 100644
--- a/src/groupdef.h
+++ b/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,
diff --git a/templates/general/layout_default.xml b/templates/general/layout_default.xml
index cf0110016cc..ac589a90509 100644
--- a/templates/general/layout_default.xml
+++ b/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=""/>