Update Doxygen doxyfile (#903)

* doxygen: don't look in mythtv/contrib Since 93e7287, it has been excluded by EXCLUDE_PATTERNS. * doxyfile: enable FULL_PATH_NAMES This makes it easier to see where a file is included. STRIP_FROM_PATH = ../../ makes all paths referenced to the root of the Git repository (assuming doxygen is run in mythtv/docs/) * doxyfile: set STRIP_FROM_INC_PATH This makes the recommended include line more useful on class documentation pages. Instead of listing just the filename, it gives a usable path for the libraries and tells you which library, program, or plugin the class is in. * doxyfile: increase LOOKUP_CACHE_SIZE * doxyfile: extract anonymous namespaces * doxyfile: enable builtin STL support * doxyfile: generate SVGs instead of PNGs * docs: these are pages or sub-pages not groups * doxyfile: update EXCLUDE_PATTERNS All moc_*.(h|cpp) files are in a moc folder. All obj folders are generated during build. The i18n folders in mythplugins only contain generated files. I considered adding: */external/* but I'm leaving it for mythtranscode/external/replex */scripts/* I don't think any of these are useful to doxygen, but I'm not sure. * doxygen-architecture-document.cpp: silence doxygen warnings 402: warning: end of comment block while expecting command </em> 401: warning: found </em> tag without matching <em> Also removed extraneous character preventing line break from working correctly.
MythTV · Jul 5, 2024 · 2b07fe4 · 2b07fe4
1 parent 8dbc67e
commit 2b07fe4
Show file tree

Hide file tree

Showing 5 changed files with 57 additions and 18 deletions.
diff --git a/mythtv/docs/CMakeLists.txt b/mythtv/docs/CMakeLists.txt
@@ -24,12 +24,19 @@ file(CREATE_LINK ${CMAKE_CURRENT_SOURCE_DIR}/doxygen-create-developer-docs.cfg
 #
 set(SOURCES_LIST
     "${CMAKE_CURRENT_SOURCE_DIR}/doxygen-architecture-document.cpp"
-    "${PROJECT_SOURCE_DIR}/contrib" "${PROJECT_SOURCE_DIR}/libs"
+    "${PROJECT_SOURCE_DIR}/libs"
     "${PROJECT_SOURCE_DIR}/programs" "${PROJECT_SOURCE_DIR}/../mythplugins")
 list(JOIN SOURCES_LIST " " DOXYGEN_SOURCES)
 
 set(DOXYGEN_EXCLUDES "${PROJECT_SOURCE_DIR}/libs/libmythmpeg2")
 
+set(DOXYGEN_STRIP_FROM_PATH "${PROJECT_SOURCE_DIR}/../")
+
+set(STRIP_FROM_INC_PATH_LIST
+    "${PROJECT_SOURCE_DIR}/libs"
+    "${PROJECT_SOURCE_DIR}/programs" "${PROJECT_SOURCE_DIR}/../")
+list(JOIN STRIP_FROM_INC_PATH_LIST " " DOXYGEN_STRIP_FROM_INC_PATH)
+
 configure_file(doxygen-paths.cfg.inc.in doxygen-paths.cfg.inc @ONLY)
 
 # Command to create documentation

diff --git a/mythtv/docs/Makefile b/mythtv/docs/Makefile
@@ -1,7 +1,9 @@
 TARGETS = devdocs
 
-DOXYGEN_SOURCES=doxygen-architecture-document.cpp ../contrib ../libs ../programs ../../mythplugins
+DOXYGEN_SOURCES=doxygen-architecture-document.cpp ../libs ../programs ../../mythplugins
 DOXYGEN_EXCLUDES=../libs/libmythmpeg2
+DOXYGEN_STRIP_FROM_PATH=../../
+DOXYGEN_STRIP_FROM_INC_PATH=../libs ../programs ../../
 
 all: $(TARGETS)
 clean:
@@ -13,6 +15,8 @@ doxygen-paths.cfg.inc: doxygen-paths.cfg.inc.in
 	@echo Creating doxygen-paths.cfg.inc
 	@sed -e "s#@DOXYGEN_SOURCES@#${DOXYGEN_SOURCES}#g" \
 	    -e "s#@DOXYGEN_EXCLUDES@#${DOXYGEN_EXCLUDES}#g" \
+	    -e "s#@DOXYGEN_STRIP_FROM_PATH@#${DOXYGEN_STRIP_FROM_PATH}#g" \
+	    -e "s#@DOXYGEN_STRIP_FROM_INC_PATH@#${DOXYGEN_STRIP_FROM_INC_PATH}#g" \
 	    doxygen-paths.cfg.inc.in > doxygen-paths.cfg.inc
 
 devdocs: doxygen-paths.cfg.inc

diff --git a/mythtv/docs/doxygen-architecture-document.cpp b/mythtv/docs/doxygen-architecture-document.cpp
@@ -398,11 +398,13 @@ state changing commands should not be issued.
 
 \ingroup libmyth
 
-MythPlugins are shared object files (_i.e._libraries) which are loaded
-from a specific directory (_%e.g._ /usr/local/lib/mythtv/plugins).
+<p>
+MythPlugins are shared object files (_i.e._ libraries) which are loaded
+from a specific directory (_e.g._ /usr/local/lib/mythtv/plugins).
 Currently, all plugins are written in the C++ language, but there is nothing
 preventing other languages being used (the functions are in the C name space).
-c
+</p>
+
 int mythplugin_init(const char *libversion); is invoked whenever mythfrontend
 is started. This typically handles upgrading any database records - it will be
 the first method called after a new version of the plugin has been installed.
@@ -627,7 +629,7 @@ See mythplugins/mythweb/modules/_shared/lang/translations.txt for more info.
 
  */
 
-/** \defgroup qobject_dangers QObject is dangerous for your health
+/** \page qobject_dangers QObject is dangerous for your health
 
 QObject derived classes can be quite useful, they can send and receive
 signals, get keyboard events, translate strings into another language
@@ -744,7 +746,7 @@ wrong slots.
 
 */
 
-/** \defgroup profiling_mythtv    Profiling MythTV
+/** \page profiling_mythtv    Profiling MythTV
 
 You can use any sampling profiler to profile %MythTV, the most
 popular GPL one is OProfile and this section tells you how to
@@ -898,7 +900,7 @@ an annotated versions of the code, and saving results.
 
 */
 
-/** \defgroup testing    Testing hints and shortcuts
+/** \page testing    Testing hints and shortcuts
 
 The internal video playback can be tested by the programs/mythavtest tool:
 

diff --git a/mythtv/docs/doxygen-create-developer-docs.cfg b/mythtv/docs/doxygen-create-developer-docs.cfg
@@ -148,7 +148,7 @@ INLINE_INHERITED_MEMB  = NO
 # shortest path that makes the file name unique will be used
 # The default value is: YES.
 
-FULL_PATH_NAMES        = NO
+FULL_PATH_NAMES        = YES
 
 # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
 # Stripping is only done if one of the specified strings matches the left-hand
@@ -160,7 +160,9 @@ FULL_PATH_NAMES        = NO
 # will be relative from the directory where doxygen is started.
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
-STRIP_FROM_PATH        =
+#Already included.
+#@INCLUDE = doxygen-paths.cfg.inc
+#STRIP_FROM_PATH        = ../../
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which
@@ -169,7 +171,9 @@ STRIP_FROM_PATH        =
 # specify the list of include paths that are normally passed to the compiler
 # using the -I flag.
 
-STRIP_FROM_INC_PATH    =
+#Already included.
+#@INCLUDE = doxygen-paths.cfg.inc
+#STRIP_FROM_INC_PATH    = ../libs ../programs ../../
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
 # less readable) file names. This can be useful is your file systems doesn't
@@ -351,7 +355,7 @@ AUTOLINK_SUPPORT       = YES
 # diagrams that involve STL classes more complete and accurate.
 # The default value is: NO.
 
-BUILTIN_STL_SUPPORT    = NO
+BUILTIN_STL_SUPPORT    = YES
 
 # If you use Microsoft's C++/CLI language, you should set this option to YES to
 # enable parsing support.
@@ -444,7 +448,7 @@ TYPEDEF_HIDES_STRUCT   = NO
 # the optimal cache size from a speed point of view.
 # Minimum value: 0, maximum value: 9, default value: 0.
 
-LOOKUP_CACHE_SIZE      = 2
+LOOKUP_CACHE_SIZE      = 3
 
 #---------------------------------------------------------------------------
 # Build related configuration options
@@ -507,7 +511,7 @@ EXTRACT_LOCAL_METHODS  = NO
 # are hidden.
 # The default value is: NO.
 
-EXTRACT_ANON_NSPACES   = NO
+EXTRACT_ANON_NSPACES   = YES
 
 # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all
 # undocumented members inside documented classes or files. If set to NO these
@@ -891,8 +895,9 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = moc_*.cpp \
-                         moc_*.h \
+EXCLUDE_PATTERNS       = */moc/* \
+                         */obj/* \
+                         */i18n/* \
                          */contrib/* \
                          */test/* \
                          */.git
@@ -2480,7 +2485,7 @@ DIRECTORY_GRAPH        = YES
 # The default value is: png.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = svg
 
 # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
 # enable generation of interactive SVG images that allow zooming and panning.
@@ -2492,7 +2497,7 @@ DOT_IMAGE_FORMAT       = png
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-INTERACTIVE_SVG        = NO
+INTERACTIVE_SVG        = YES
 
 # The DOT_PATH tag can be used to specify the path where the dot tool can be
 # found. If left blank, it is assumed the dot tool can be found in the path.

diff --git a/mythtv/docs/doxygen-paths.cfg.inc.in b/mythtv/docs/doxygen-paths.cfg.inc.in
@@ -14,3 +14,24 @@ INPUT                  = @DOXYGEN_SOURCES@
 # run.
 
 EXCLUDE                = @DOXYGEN_EXCLUDES@
+
+# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
+# Stripping is only done if one of the specified strings matches the left-hand
+# part of the path. The tag can be used to show relative paths in the file list.
+# If left blank the directory from which doxygen is run is used as the path to
+# strip.
+#
+# Note that you can specify absolute paths here, but also relative paths, which
+# will be relative from the directory where doxygen is started.
+# This tag requires that the tag FULL_PATH_NAMES is set to YES.
+
+STRIP_FROM_PATH        = @DOXYGEN_STRIP_FROM_PATH@
+
+# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
+# path mentioned in the documentation of a class, which tells the reader which
+# header file to include in order to use a class. If left blank only the name of
+# the header file containing the class definition is used. Otherwise one should
+# specify the list of include paths that are normally passed to the compiler
+# using the -I flag.
+
+STRIP_FROM_INC_PATH    = @DOXYGEN_STRIP_FROM_INC_PATH@