More flexible include graphs regarding show / hide

For the `INCLUDE_GRAPH` and the `INCLUDED_BY_GRAPH` it is possible to get a warning like:
```
warning: Included by graph for 'includes.h' not generated, too many nodes (268), threshold is 250. Consider increasing DOT_GRAPH_MAX_NODES.
```

This warning is quite disruptive especially in case `WARN_AS_ERROR` is set. The only way to prevent the warning and its consequences is to increase the `DOT_GRAPH_MAX_NODES` meaning there there might be some very large graphs (also at other places) or the set `INCLUDED_BY_GRAPH=NO` meaning, potential, loosing quite a few useful graphs.
For call / caller graphs it is possible to steer the graph creation process on a 1 to 1 base (commands like `\callgraph` and `\hidecallgraph`).

Introducing for the include graphs:
- `\includegraph` and `\hideincludegraph`
- `\includedbygraph` and `\hideincludedbygraph`

Note: we needed  to set in the `layout_defailt.xml`:
```
    <includegraph visible="yes"/>
    <includedbygraph visible="yes"/>
```
as otherwise `\includegraph`and `\includedbygraph` won't work.

doc/commands.doc

@@ -118,6 +118,8 @@ documentation:
 \refitem cmdheaderfile \\headerfile
 \refitem cmdhidecallergraph \\hidecallergraph
 \refitem cmdhidecallgraph \\hidecallgraph
+\refitem cmdhideincludedbygraph \\hideincludedbygraph
+\refitem cmdhideincludegraph \\hideincludegraph
 \refitem cmdhiderefby \\hiderefby
 \refitem cmdhiderefs \\hiderefs
 \refitem cmdhideinitializer \\hideinitializer
@@ -130,6 +132,8 @@ documentation:
 \refitem cmdimplements \\implements
 \refitem cmdinclude \\include
 \refitem cmdincludedoc \\includedoc
+\refitem cmdincludedbygraph \\includedbygraph
+\refitem cmdincludegraph \\includegraph
 \refitem cmdincludelineno \\includelineno
 \refitem cmdingroup \\ingroup
 \refitem cmdinternal \\internal
@@ -426,6 +430,62 @@ Structural indicators
       section \ref cmdhiderefby "\\hiderefby" and
       option \ref cfg_references_relation "REFERENCES_RELATION"
 
+<hr>
+\section cmdincludegraph \\includegraph
+
+  \addindex \\includegraph
+  When this command is put in a comment block of a file
+  then doxygen will generate an include graph for that file. The
+  include graph will be generated regardless of the value of
+  \ref cfg_include_graph "INCLUDE_GRAPH".
+
+  \sa section \ref cmdhideincludegraph "\\hideincludegraph",
+      section \ref cmdincludedbygraph "\\includedbygraph",
+      section \ref cmdhideincludedbygraph "\\hideincludedbygraph" and
+      option \ref cfg_include_graph "INCLUDE_GRAPH"
+
+<hr>
+\section cmdhideincludegraph \\hideincludegraph
+
+  \addindex \\hideincludegraph
+  When this command is put in a comment block of a file
+  then doxygen will not generate an include graph for that file. The
+  include graph will not be generated regardless of the value of
+  \ref cfg_include_graph "INCLUDE_GRAPH".
+
+  \sa section \ref cmdincludegraph "\\includegraph",
+      section \ref cmdincludedbygraph "\\includedbygraph",
+      section \ref cmdhideincludedbygraph "\\hideincludedbygraph" and
+      option \ref cfg_include_graph "INCLUDE_GRAPH"
+
+<hr>
+\section cmdincludedbygraph \\includedbygraph
+
+  \addindex \\includedbygraph
+  When this command is put in a comment block of an include file
+  then doxygen will generate an included by graph for that include file. The
+  included by graph will be generated regardless of the value of
+  \ref cfg_included_by_graph "INCLUDED_BY_GRAPH".
+
+  \sa section \ref cmdhideincludedbygraph "\\hideincludedbygraph",
+      section \ref cmdincludegraph "\\ncludegraph",
+      section \ref cmdhideincludegraph "\\hideincludegraph" and
+      option \ref cfg_included_by_graph "INCLUDED_BY_GRAPH"
+
+<hr>
+\section cmdhideincludedbygraph \\hideincludedbygraph
+
+  \addindex \\hideincludedbygraph
+  When this command is put in a comment block of an include file
+  then doxygen will not generate an included by graph for that include file. The
+  included by graph will not be generated regardless of the value of
+  \ref cfg_included_by_graph "INCLUDED_BY_GRAPH".
+
+  \sa section \ref cmdincludedbygraph "\\includedbygraph",
+      section \ref cmdincludegraph "\\ncludegraph",
+      section \ref cmdhideincludegraph "\\hideincludegraph" and
+      option \ref cfg_included_by_graph "INCLUDED_BY_GRAPH"
+
 <hr>
 \section cmdqualifier \\qualifier <label> | "(text)"
 

src/commentscan.l

@@ -124,6 +124,10 @@ static bool handleCallgraph(yyscan_t yyscanner,const QCString &, const StringVec
 static bool handleHideCallgraph(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleCallergraph(yyscan_t yyscanner,const QCString &, const StringVector &);
 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 handleHideIncludegraph(yyscan_t yyscanner,const QCString &, const StringVector &);
+static bool handleHideIncludedBygraph(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleReferencedByRelation(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleHideReferencedByRelation(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleReferencesRelation(yyscan_t yyscanner,const QCString &, const StringVector &);
@@ -222,6 +226,8 @@ static const std::map< std::string, DocCmdMap > docCmdMap =
   { "headerfile",      { &handleHeaderFile,       CommandSpacing::Invisible }},
   { "hidecallergraph", { &handleHideCallergraph,  CommandSpacing::Invisible }},
   { "hidecallgraph",   { &handleHideCallgraph,    CommandSpacing::Invisible }},
+  { "hideincludedbygraph", { &handleHideIncludedBygraph, CommandSpacing::Invisible }},
+  { "hideincludegraph",    { &handleHideIncludegraph,    CommandSpacing::Invisible }},
   { "hideinitializer", { &handleHideInitializer,  CommandSpacing::Invisible }},
   { "hiderefby",       { &handleHideReferencedByRelation, CommandSpacing::Invisible }},
   { "hiderefs",        { &handleHideReferencesRelation,   CommandSpacing::Invisible }},
@@ -233,6 +239,8 @@ static const std::map< std::string, DocCmdMap > docCmdMap =
   { "image",           { &handleImage,            CommandSpacing::Block     }},
   { "implements",      { &handleExtends,          CommandSpacing::Invisible }},
   { "include",         { 0,                       CommandSpacing::Block     }},
+  { "includedbygraph", { &handleIncludedBygraph,  CommandSpacing::Invisible }},
+  { "includegraph",    { &handleIncludegraph,     CommandSpacing::Invisible }},
   { "includelineno",   { 0,                       CommandSpacing::Block     }},
   { "ingroup",         { &handleIngroup,          CommandSpacing::Invisible }},
   { "inherit",         { &handleInherit,          CommandSpacing::Invisible }},
@@ -3036,6 +3044,34 @@ static bool handleHideCallergraph(yyscan_t yyscanner,const QCString &, const Str
   return FALSE;
 }
 
+static bool handleIncludegraph(yyscan_t yyscanner,const QCString &, const StringVector &)
+{
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  yyextra->current->includeGraph = TRUE; // ON
+  return FALSE;
+}
+
+static bool handleIncludedBygraph(yyscan_t yyscanner,const QCString &, const StringVector &)
+{
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  yyextra->current->includedByGraph = TRUE; // ON
+  return FALSE;
+}
+
+static bool handleHideIncludegraph(yyscan_t yyscanner,const QCString &, const StringVector &)
+{
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  yyextra->current->includeGraph = FALSE; // OFF
+  return FALSE;
+}
+
+static bool handleHideIncludedBygraph(yyscan_t yyscanner,const QCString &, const StringVector &)
+{
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  yyextra->current->includedByGraph = 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

@@ -3835,6 +3835,10 @@ UML notation for the relationships.
  tags are set to \c YES then doxygen will generate a graph for each documented file
  showing the direct and indirect include dependencies of the file with other
  documented files.
+ Explicit enabling an include graph, when \c INCLUDE_GRAPH is is set to \c NO, can be
+ accomplished by means of the command \ref cmdincludegraph "\\includegraph".
+ Disabling an include graph can be accomplished by means of the command
+ \ref cmdhideincludegraph "\\hideincludegraph".
 ]]>
       </docs>
     </option>
@@ -3846,6 +3850,10 @@ UML notation for the relationships.
  tags are set to \c YES then doxygen will generate a graph for each documented file
  showing the direct and indirect include dependencies of the file with other
  documented files.
+ Explicit enabling an included by graph, when \c INCLUDED_BY_GRAPH is set to \c NO, can be
+ accomplished by means of the command \ref cmdincludedbygraph "\\includedbygraph".
+ Disabling an included by graph can be accomplished by means of the command
+ \ref cmdhideincludedbygraph "\\hideincludedbygraph".
 ]]>
       </docs>
     </option>

src/context.cpp

@@ -2795,15 +2795,18 @@ class FileContext::Private : public DefinitionContext<FileContext::Private>
     TemplateVariant hasIncludeGraph() const
     {
       bool haveDot = Config_getBool(HAVE_DOT);
-      DotInclDepGraphPtr incGraph = getIncludeGraph();
-      return (haveDot && !incGraph->isTooBig() && !incGraph->isTrivial());
+      if (haveDot && m_fileDef->hasIncludeGraph())
+      {
+        DotInclDepGraphPtr incGraph = getIncludeGraph();
+        return !incGraph->isTooBig() && !incGraph->isTrivial();
+      }
+      return TemplateVariant(FALSE);
     }
     TemplateVariant includeGraph() const
     {
-      bool haveDot = Config_getBool(HAVE_DOT);
-      TextStream t;
-      if (haveDot)
+      if (hasIncludeGraph().toBool())
       {
+        TextStream t;
         DotInclDepGraphPtr cg = getIncludeGraph();
         QCString fn = m_fileDef->getOutputFileBase();
         addHtmlExtensionIfMissing(fn);
@@ -2833,21 +2836,28 @@ class FileContext::Private : public DefinitionContext<FileContext::Private>
             break;
         }
         g_globals.dynSectionId++;
+        return TemplateVariant(t.str().c_str(),TRUE);
+      }
+      else
+      {
+        return TemplateVariant("");
       }
-      return TemplateVariant(t.str().c_str(),TRUE);
     }
     TemplateVariant hasIncludedByGraph() const
     {
       bool haveDot = Config_getBool(HAVE_DOT);
-      DotInclDepGraphPtr incGraph = getIncludedByGraph();
-      return (haveDot && !incGraph->isTooBig() && !incGraph->isTrivial());
+      if (haveDot && m_fileDef->hasIncludedByGraph())
+      {
+        DotInclDepGraphPtr incGraph = getIncludedByGraph();
+        return !incGraph->isTooBig() && !incGraph->isTrivial();
+      }
+      return TemplateVariant(FALSE);
     }
     TemplateVariant includedByGraph() const
     {
-      bool haveDot = Config_getBool(HAVE_DOT);
-      TextStream t;
-      if (haveDot)
+      if (hasIncludedByGraph().toBool())
       {
+        TextStream t;
         DotInclDepGraphPtr cg = getIncludedByGraph();
         QCString fn = m_fileDef->getOutputFileBase();
         addHtmlExtensionIfMissing(fn);
@@ -2877,8 +2887,12 @@ class FileContext::Private : public DefinitionContext<FileContext::Private>
             break;
         }
         g_globals.dynSectionId++;
+        return TemplateVariant(t.str().c_str(),TRUE);
+      }
+      else
+      {
+        return TemplateVariant("");
       }
-      return TemplateVariant(t.str().c_str(),TRUE);
     }
 
   private:

src/doxygen.cpp

@@ -507,6 +507,8 @@ static void buildFileList(const Entry *root)
       fd->setBriefDescription(root->brief,root->briefFile,root->briefLine);
       fd->addSectionsToDefinition(root->anchors);
       fd->setRefItems(root->sli);
+      fd->enableIncludeGraph(root->includeGraph);
+      fd->enableIncludedByGraph(root->includedByGraph);
       for (const Grouping &g : root->groups)
       {
         GroupDef *gd=0;

src/entry.cpp

@@ -65,6 +65,8 @@ Entry::Entry(const Entry &e)
   subGrouping = e.subGrouping;
   callGraph   = e.callGraph;
   callerGraph = e.callerGraph;
+  includeGraph = e.includeGraph;
+  includedByGraph = e.includedByGraph;
   referencedByRelation = e.referencedByRelation;
   referencesRelation   = e.referencesRelation;
   virt        = e.virt;
@@ -187,6 +189,8 @@ void Entry::reset()
   bool entryCallerGraph = Config_getBool(CALLER_GRAPH);
   bool entryReferencedByRelation = Config_getBool(REFERENCED_BY_RELATION);
   bool entryReferencesRelation   = Config_getBool(REFERENCES_RELATION);
+  bool entryIncludeGraph    = Config_getBool(INCLUDE_GRAPH);
+  bool entryIncludedByGraph = Config_getBool(INCLUDED_BY_GRAPH);
   //printf("Entry::reset()\n");
   name.resize(0);
   type.resize(0);
@@ -219,6 +223,8 @@ void Entry::reset()
   mGrpId = -1;
   callGraph   = entryCallGraph;
   callerGraph = entryCallerGraph;
+  includeGraph = entryIncludeGraph;
+  includedByGraph = entryIncludedByGraph;
   referencedByRelation = entryReferencedByRelation;
   referencesRelation   = entryReferencesRelation;
   section = EMPTY_SEC;

src/entry.h

@@ -255,6 +255,8 @@ class Entry
     bool callerGraph;         //!< do we need to draw the caller graph?
     bool referencedByRelation;//!< do we need to show the referenced by relation?
     bool referencesRelation;  //!< do we need to show the references relation?
+    bool includeGraph;        //!< do we need to draw the include graph?
+    bool includedByGraph;     //!< do we need to draw the included by graph?
     Specifier    virt;        //!< virtualness of the entry
     QCString     args;        //!< member argument string
     QCString     bitfields;   //!< member's bit fields

src/filedef.cpp

@@ -136,6 +136,11 @@ class FileDefImpl : public DefinitionMixin<FileDef>
     virtual void addIncludedUsingDirectives(FileDefSet &visitedFiles) override;
     virtual void addListReferences() override;
 
+    virtual bool hasIncludeGraph() const override;
+    virtual bool hasIncludedByGraph() const override;
+    virtual void enableIncludeGraph(bool e) override;
+    virtual void enableIncludedByGraph(bool e) override;
+
   private:
     void setDiskNameLocal(const QCString &name);
     void acquireFileVersion();
@@ -189,6 +194,9 @@ class FileDefImpl : public DefinitionMixin<FileDef>
     ClassLinkedRefMap     m_exceptions;
     ConceptLinkedRefMap   m_concepts;
     bool                  m_subGrouping;
+    bool                  m_hasIncludeGraph = false;
+    bool                  m_hasIncludedByGraph = false;
+
 };
 
 std::unique_ptr<FileDef> createFileDef(const QCString &p,const QCString &n,const QCString &ref,const QCString &dn)
@@ -577,7 +585,7 @@ void FileDefImpl::writeIncludeFiles(OutputList &ol)
 
 void FileDefImpl::writeIncludeGraph(OutputList &ol)
 {
-  if (Config_getBool(HAVE_DOT) /*&& Config_getBool(INCLUDE_GRAPH)*/)
+  if (Config_getBool(HAVE_DOT) && m_hasIncludeGraph /*&& Config_getBool(INCLUDE_GRAPH)*/)
   {
     //printf("Graph for file %s\n",qPrint(name()));
     DotInclDepGraph incDepGraph(this,FALSE);
@@ -602,7 +610,7 @@ void FileDefImpl::writeIncludeGraph(OutputList &ol)
 
 void FileDefImpl::writeIncludedByGraph(OutputList &ol)
 {
-  if (Config_getBool(HAVE_DOT) /*&& Config_getBool(INCLUDED_BY_GRAPH)*/)
+  if (Config_getBool(HAVE_DOT) && m_hasIncludedByGraph /*&& Config_getBool(INCLUDED_BY_GRAPH)*/)
   {
     //printf("Graph for file %s\n",qPrint(name()));
     DotInclDepGraph incDepGraph(this,TRUE);
@@ -1740,6 +1748,26 @@ int FileDefImpl::numDecMembers() const
   return ml ? ml->numDecMembers() : 0;
 }
 
+void FileDefImpl::enableIncludeGraph(bool e)
+{
+  m_hasIncludeGraph=e;
+}
+
+void FileDefImpl::enableIncludedByGraph(bool e)
+{
+  m_hasIncludedByGraph=e;
+}
+
+bool FileDefImpl::hasIncludeGraph() const
+{
+  return m_hasIncludeGraph;
+}
+
+bool FileDefImpl::hasIncludedByGraph() const
+{
+  return m_hasIncludedByGraph;
+}
+
 // -----------------------
 
 bool compareFileDefs(const FileDef *fd1, const FileDef *fd2)

src/filedef.h

@@ -188,6 +188,13 @@ class FileDef : public DefinitionMutable, public Definition
     virtual void addIncludedUsingDirectives(FileDefSet &visitedFiles) = 0;
 
     virtual void addListReferences() = 0;
+
+    // include graph related members
+    virtual bool hasIncludeGraph() const = 0;
+    virtual bool hasIncludedByGraph() const = 0;
+
+    virtual void enableIncludeGraph(bool e) = 0;
+    virtual void enableIncludedByGraph(bool e) = 0;
 };
 
 std::unique_ptr<FileDef> createFileDef(const QCString &p,const QCString &n,const QCString &ref=QCString(),const QCString &dn=QCString());

templates/general/layout_default.xml

@@ -143,8 +143,8 @@
   <file>
     <briefdescription visible="yes"/>
     <includes visible="$SHOW_INCLUDE_FILES"/>
-    <includegraph visible="$INCLUDE_GRAPH"/>
-    <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
+    <includegraph visible="yes"/>
+    <includedbygraph visible="yes"/>
     <sourcelink visible="yes"/>
     <memberdecl>
       <interfaces visible="yes" title=""/>