Merge branch 'doxygen-fixes'

Fix several problems in Doxygen markup and update the required Doxygen version to 1.8.17. Closes #19126.
2022-03-28 00:47:28 +02:00
parent 9af728caea c1ee60395a
commit 7769894304
8 changed files with 56 additions and 54 deletions
--- a/docs/doxygen/Doxyfile
+++ b/docs/doxygen/Doxyfile
@@ -29,7 +29,6 @@ MULTILINE_CPP_IS_BRIEF = NO
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 4
-TCL_SUBST              =
 OPTIMIZE_OUTPUT_FOR_C  = NO
 OPTIMIZE_OUTPUT_JAVA   = NO
 OPTIMIZE_FOR_FORTRAN   = NO
@@ -60,44 +59,44 @@ LOOKUP_CACHE_SIZE      = 0
 #---------------------------------------------------------------------------

 # aliases to be used by classes which emit wxEvents (e.g. wxWindow, wxTextCtrl, etc):
-ALIASES = beginEventEmissionTable="\n<h2>Events emitted by this class</h2><p>Event macros for events emitted by this class:</p><div>"
-ALIASES += beginEventEmissionTable{1}="\n<h2>Events emitted by this class</h2><p>The following event handler macros redirect the events to member function handlers '<b>func</b>' with prototypes like: <div class='eventHandler'><span>void&nbsp;handlerFuncName(\1&&nbsp;event)</span></div></p>Event macros for events emitted by this class:<div>"
-ALIASES += beginEventEmissionTable{2}="\n<h2>Events emitted by this class</h2><p>The following event handler macros redirect the events to member function handlers '<b>func</b>' with prototypes like: <div class='eventHandler'><span>void&nbsp;handlerFuncName(\1&&nbsp;event)</span> or <span>void&nbsp;handlerFuncName(\2&&nbsp;event)</span></div></p>Event macros for events emitted by this class:<div>"
+ALIASES = beginEventEmissionTable="^^<h2>Events emitted by this class</h2><p>Event macros for events emitted by this class:</p><div>"
+ALIASES += beginEventEmissionTable{1}="^^<h2>Events emitted by this class</h2><p>The following event handler macros redirect the events to member function handlers '<b>func</b>' with prototypes like: <div class='eventHandler'><span>void&nbsp;handlerFuncName(\1&&nbsp;event)</span></div></p>Event macros for events emitted by this class:<div>"
+ALIASES += beginEventEmissionTable{2}="^^<h2>Events emitted by this class</h2><p>The following event handler macros redirect the events to member function handlers '<b>func</b>' with prototypes like: <div class='eventHandler'><span>void&nbsp;handlerFuncName(\1&&nbsp;event)</span> or <span>void&nbsp;handlerFuncName(\2&&nbsp;event)</span></div></p>Event macros for events emitted by this class:<div>"

 # aliases to be used in wxEvent-derived classes:
-ALIASES += beginEventTable{1}="\n<h2>Events using this class</h2><p>The following event handler macros redirect the events to member function handlers '<b>func</b>' with prototypes like: <div class='eventHandler'><span>void&nbsp;handlerFuncName(\1&&nbsp;event)</span></div></p>Event macros:<div>"
-ALIASES += beginEventTable{2}="\n<h2>Events using this class</h2><p>The following event handler macros redirect the events to member function handlers '<b>func</b>' with prototypes like: <div class='eventHandler'><span>void&nbsp;handlerFuncName(\1&&nbsp;event)</span> or <span>void&nbsp;handlerFuncName(\2&&nbsp;event)</span></div></p>Event macros:<div>"
+ALIASES += beginEventTable{1}="^^<h2>Events using this class</h2><p>The following event handler macros redirect the events to member function handlers '<b>func</b>' with prototypes like: <div class='eventHandler'><span>void&nbsp;handlerFuncName(\1&&nbsp;event)</span></div></p>Event macros:<div>"
+ALIASES += beginEventTable{2}="^^<h2>Events using this class</h2><p>The following event handler macros redirect the events to member function handlers '<b>func</b>' with prototypes like: <div class='eventHandler'><span>void&nbsp;handlerFuncName(\1&&nbsp;event)</span> or <span>void&nbsp;handlerFuncName(\2&&nbsp;event)</span></div></p>Event macros:<div>"

 # common event aliases:
 ALIASES += event{1}="</div>\li <span class='event'>\1</span>:<div class='eventDesc'>"
 ALIASES += event{2}="</div>\li <span class='event'>\1, \2</span>:<div class='eventDesc'>"
 ALIASES += event{3}="</div>\li <span class='event'>\1, \2, \3</span>:<div class='eventDesc'>"
 ALIASES += event{4}="</div>\li <span class='event'>\1, \2, \3, \4</span>:<div class='eventDesc'>"
-ALIASES += endEventTable="</div>\n"
+ALIASES += endEventTable="</div>^^"

 # style aliases
-ALIASES += beginStyleTable="\n<h2>Styles</h2><p>This class supports the following styles:</p><div>"
+ALIASES += beginStyleTable="^^<h2>Styles</h2><p>This class supports the following styles:</p><div>"
 ALIASES += style{1}="</div>\li <span class='style'>\1</span>:<div class='styleDesc'>"
-ALIASES += endStyleTable="</div>\n"
+ALIASES += endStyleTable="</div>^^"

 # extra style aliases
-ALIASES += beginExtraStyleTable="\n<hr><h2>Extra Styles</h2><p>This class supports the following extra styles:</p><div>"
-ALIASES += endExtraStyleTable="</div>\n"
+ALIASES += beginExtraStyleTable="^^<hr><h2>Extra Styles</h2><p>This class supports the following extra styles:</p><div>"
+ALIASES += endExtraStyleTable="</div>^^"

 # flag aliases
 ALIASES += beginFlagTable="<div>"
 ALIASES += flag{1}="</div>\li <span class='flag'>\1</span>:<div class='flagDesc'>"
-ALIASES += endFlagTable="</div>\n"
+ALIASES += endFlagTable="</div>^^"

 # creates appearance section: this should be used for all main GUI controls
 # that look different in different ports. genericAppearance can be used for the
 # controls that always look the same.
-ALIASES += appearance{1}="\htmlonly<div class='appearance'><span class='appearance'>Appearance:</span><table><tr><td>\endhtmlonly\n\image html appear-\1-msw.png \"wxMSW Appearance\"\n\htmlonly</td><td>\endhtmlonly\n\image html appear-\1-gtk.png \"wxGTK Appearance\"\n\htmlonly</td><td>\endhtmlonly\n\image html appear-\1-mac.png \"wxOSX Appearance\"\n\htmlonly</td></tr></table></div>\endhtmlonly"
-ALIASES += genericAppearance{1}="\htmlonly<div class='appearance'><span class='appearance'>Appearance:</span><table class='appearance'><tr><td>\endhtmlonly\n\image html generic/\1.png \"Generic Appearance\"\n\htmlonly</td></tr></table></div>\endhtmlonly"
+ALIASES += appearance{1}="\htmlonly<div class='appearance'><span class='appearance'>Appearance:</span><table><tr><td>\endhtmlonly^^\image html appear-\1-msw.png \"wxMSW Appearance\"^^\htmlonly</td><td>\endhtmlonly^^\image html appear-\1-gtk.png \"wxGTK Appearance\"^^\htmlonly</td><td>\endhtmlonly^^\image html appear-\1-mac.png \"wxOSX Appearance\"^^\htmlonly</td></tr></table></div>\endhtmlonly"
+ALIASES += genericAppearance{1}="\htmlonly<div class='appearance'><span class='appearance'>Appearance:</span><table class='appearance'><tr><td>\endhtmlonly^^\image html generic/\1.png \"Generic Appearance\"^^\htmlonly</td></tr></table></div>\endhtmlonly"

 # these compact versions are only used on the screenshots page
-ALIASES += appearance_brief{2}="\htmlonly<div class='appearance_brief'><table><tr><td>\endhtmlonly\n\1\htmlonly</td><td>\endhtmlonly\n\image html appear-\2-msw.png\n\htmlonly</td><td>\endhtmlonly\n\image html appear-\2-gtk.png\n\htmlonly</td><td>\endhtmlonly\n\image html appear-\2-mac.png\n\htmlonly</td></tr></table></div>\endhtmlonly"
-ALIASES += genericAppearance_brief{2}="\htmlonly<div class='appearance_brief'><table><tr><td>\endhtmlonly\n\1\htmlonly</td><td>\endhtmlonly\n\image html generic/\2.png\n\htmlonly</td></tr></table></div>\endhtmlonly"
+ALIASES += appearance_brief{2}="\htmlonly<div class='appearance_brief'><table><tr><td>\endhtmlonly^^\1\htmlonly</td><td>\endhtmlonly^^\image html appear-\2-msw.png ^^\htmlonly</td><td>\endhtmlonly^^\image html appear-\2-gtk.png ^^\htmlonly</td><td>\endhtmlonly^^\image html appear-\2-mac.png ^^\htmlonly</td></tr></table></div>\endhtmlonly"
+ALIASES += genericAppearance_brief{2}="\htmlonly<div class='appearance_brief'><table><tr><td>\endhtmlonly^^\1\htmlonly</td><td>\endhtmlonly^^\image html generic/\2.png ^^\htmlonly</td></tr></table></div>\endhtmlonly"

 # aliases for the creation of "named member groups"
 # USAGE: the first argument must not contain spaces and be a unique identifier
@@ -113,9 +112,9 @@ ALIASES += ref_member_group{2}="<a href='#\1' class='el'>\2</a>"
 #---------------------------------------------------------------------------

 # aliases for additional wx-specific infos
-ALIASES += category{1}="\ingroup group_class_\1 \n<div><span class='category'>Category:</span>&nbsp;&nbsp;<span class='category_text'>\ref group_class_\1</span></div>"
-ALIASES += category{2}="\ingroup group_class_\1 group_class_\2 \n<div><span class='category'>Category:</span>&nbsp;&nbsp;<span class='category_text'>\ref group_class_\1, \ref group_class_\2</span></div>"
-ALIASES += category{3}="\ingroup group_class_\1 group_class_\2 group_class_\3 \n<div><span class='category'>Category:</span>&nbsp;&nbsp;<span class='category_text'>\ref group_class_\1, \ref group_class_\2, \ref group_class_\3</span></div>"
+ALIASES += category{1}="\ingroup group_class_\1 ^^<div><span class='category'>Category:</span>&nbsp;&nbsp;<span class='category_text'>\ref group_class_\1</span></div>"
+ALIASES += category{2}="\ingroup group_class_\1 group_class_\2 ^^<div><span class='category'>Category:</span>&nbsp;&nbsp;<span class='category_text'>\ref group_class_\1, \ref group_class_\2</span></div>"
+ALIASES += category{3}="\ingroup group_class_\1 group_class_\2 group_class_\3 ^^<div><span class='category'>Category:</span>&nbsp;&nbsp;<span class='category_text'>\ref group_class_\1, \ref group_class_\2, \ref group_class_\3</span></div>"
 ALIASES += library{1}="<h2></h2><div><span class='lib'>Library:</span>&nbsp;&nbsp;<span class='lib_text'>\ref page_libs_\1</span></div>"
 ALIASES += nolibrary="<h2></h2><div><span class='lib'>Library:</span>&nbsp;&nbsp;<span class='lib_text'>None; this class implementation is entirely header-based.</span></div>"
 ALIASES += stdobjects="<span class='stdobj'>Predefined objects/pointers:</span>"
@@ -136,7 +135,7 @@ ALIASES += onlyfor{4}="<div><span class='avail'>Availability:</span>&nbsp;&nbsp;

 # Use this in grouped global functions, and macros since they
 # wouldn't otherwise indicate what header they are defined in.
-ALIASES += header{1}="Include file:\n \verbatim #include <\1> \endverbatim"
+ALIASES += header{1}="Include file:^^ \verbatim #include <\1> \endverbatim"

 # some formatting aliases
 ALIASES += true="<span class='literal'>true</span>"
@@ -344,7 +343,6 @@ VERBATIM_HEADERS       = NO # Default: YES
 #---------------------------------------------------------------------------

 ALPHABETICAL_INDEX     = YES
-COLS_IN_ALPHA_INDEX    = 5
 IGNORE_PREFIX          = wx


@@ -545,7 +543,6 @@ GENERATE_TAGFILE       = $(GENERATE_TAGFILE)
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
 EXTERNAL_PAGES         = YES
-PERL_PATH              = /usr/bin/perl


 #---------------------------------------------------------------------------
@@ -553,7 +550,6 @@ PERL_PATH              = /usr/bin/perl
 #---------------------------------------------------------------------------

 CLASS_DIAGRAMS         = YES
-MSCGEN_PATH            =
 DIA_PATH               =
 HIDE_UNDOC_RELATIONS   = YES
 HAVE_DOT               = YES # Default: NO
@@ -580,7 +576,7 @@ DOTFILE_DIRS           =
 MSCFILE_DIRS           =
 DIAFILE_DIRS           =
 PLANTUML_JAR_PATH      =
-DOT_GRAPH_MAX_NODES    = 50
+DOT_GRAPH_MAX_NODES    = 150 # Default 50, we currently have 108 for wxObject
 MAX_DOT_GRAPH_DEPTH    = 1000 # Default: 0
 DOT_TRANSPARENT        = NO
 DOT_MULTI_TARGETS      = NO
--- a/docs/doxygen/regen.sh
+++ b/docs/doxygen/regen.sh
@@ -41,7 +41,7 @@ fi
 # Still allow using incompatible version if explicitly requested.
 if [[ -z $WX_SKIP_DOXYGEN_VERSION_CHECK ]]; then
    doxygen_version=`$DOXYGEN --version`
-    doxygen_version_required=1.8.8
+    doxygen_version_required=1.8.17
    if [[ $doxygen_version != $doxygen_version_required ]]; then
        echo "Doxygen version $doxygen_version is not supported."
        echo "Please use Doxygen $doxygen_version_required or export WX_SKIP_DOXYGEN_VERSION_CHECK."
@@ -222,7 +222,5 @@ fi
 # Doxygen has the annoying habit to put the full path of the
 # affected files in the log file; remove it to make the log
 # more readable
-currpath=`pwd`/
-interfacepath=`cd ../../interface && pwd`/
-cat doxygen.log | sed -e "s|$currpath||g" -e "s|$interfacepath||g" > temp
-mv temp doxygen.log
+topsrcdir=`cd ../.. && pwd`
+sed -i'' -e "s|$topsrcdir/||g" doxygen.log
--- a/docs/msw/gtk.md
+++ b/docs/msw/gtk.md
@@ -25,7 +25,7 @@ Regenerate required make/project files:

 3. Download GTK+ for Windows and uncompress files in the directory
 without spaces in the name. We suppose later that GTK+/Win32 is
-in the C:\gtk directory.
+in the `C:\gtk` directory.

    http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+_2.24.10-1_win32.zip

@@ -48,11 +48,11 @@ and library directory

 See http://msdn.microsoft.com/en-us/library/t9az1d21(v=vs.90).aspx

-Open solution file in build\msw directory, select "GTK+ Debug" solution
+Open solution file in `build\msw` directory, select "GTK+ Debug" solution
 configuration and build the solution. To be sure that everything is as expected
 you can build minimal sample.

-GTK+ is linked to wxWidgets always as DLL, so C:\gtk\bin directory should be
+GTK+ is linked to wxWidgets always as DLL, so `C:\gtk\bin` directory should be
 in %PATH% environment variable before application run.

 4.2 You can also build using nmake:
--- a/docs/msw/install.md
+++ b/docs/msw/install.md
@@ -42,7 +42,7 @@ The following sections explain how to compile wxWidgets with each supported
 compiler, see the "Building Applications" section about the instructions for
 building your application using wxWidgets.

-All makefiles and project are located in build\msw directory.
+All makefiles and project are located in `build\msw` directory.

 Microsoft Visual C++ Compilation       {#msw_build_msvs}
 ----------------------------------------------------------------
@@ -119,7 +119,7 @@ contributors. If the version is out of date, please [create an issue or pull req
 ### Special notes for Visual Studio 2010+

 For Visual Studio 2010+ solutions it is possible to customize the build by
-creating a `wx_local.props` file in the build\msw directory which is used, if it
+creating a `wx_local.props` file in the `build\msw` directory which is used, if it
 exists, by the projects. The settings in that file override the default values
 for the properties such as wxCfg (corresponding to the CFG makefile variable
 described below) or wxVendor (corresponding to VENDOR). The typical way to
@@ -239,7 +239,7 @@ executed from a DOS command line window (cmd.exe, *not* Bash sh.exe).
         make command without `setup_h` at the end to work around a bug
         in the current makefiles.

-2. To verify your build, change the directory to samples\minimal and
+2. To verify your build, change the directory to `samples\minimal` and
   run the same mingw32-make command (with the same parameters there),
   this should create a working minimal wxWidgets sample.

--- a/interface/wx/image.h
+++ b/interface/wx/image.h
@@ -823,6 +823,12 @@ public:

        Takes care of the mask colour and out of bounds problems.

+        @param image
+            The image containing the data to copy, must be valid.
+        @param x
+            The horizontal position of the position to copy the data to.
+        @param y
+            The vertical position of the position to copy the data to.
        @param alphaBlend
            This parameter (new in wx 3.1.5) determines whether the alpha values
            of the original image replace (default) or are composed with the
--- a/interface/wx/regex.h
+++ b/interface/wx/regex.h
@@ -33,9 +33,9 @@ enum
        Use basic regular expression syntax, close to its POSIX definition,
        but with some extensions still available.

-        The word start/end boundary assertions @c "\<" and @c "\>" are only
-        available when using basic syntax, use @c "[[:<:]] and @c "[[:>:]]" or
-        just more general word boundary assertion @c "\b" when not using it.
+        The word start/end boundary assertions `\<` and `\>` are only
+        available when using basic syntax, use `[[:<:]]` and `[[:>:]]` or
+        just more general word boundary assertion `\b` when not using it.
     */
    wxRE_BASIC    = 2,

@@ -46,9 +46,11 @@ enum
    wxRE_NOSUB    = 8,

    /**
-        If not set, treat '\n' as an ordinary character, otherwise it is
-        special: it is not matched by '.' and '^' and '$' always match
-        after/before it regardless of the setting of wxRE_NOT[BE]OL.
+        If not set, treat `\n` as an ordinary character.
+
+        Otherwise `\n` is special: it is not matched by `.` and `^` and `$`
+        always match after/before it regardless of the setting of
+        ::wxRE_NOTBOL and ::wxRE_NOTEOL.
    */
    wxRE_NEWLINE  = 16,

--- a/interface/wx/richtext/richtextprint.h
+++ b/interface/wx/richtext/richtextprint.h
@@ -44,11 +44,11 @@ enum wxRichTextPageLocation {
    You can specify the following keywords in header and footer text, which will
    be substituted for the actual values during printing and preview.

-    - @@DATE@: the current date.
-    - @@PAGESCNT@: the total number of pages.
-    - @@PAGENUM@: the current page number.
-    - @@TIME@: the current time.
-    - @@TITLE@: the title of the document, as passed to the wxRichTextPrinting or
+    - @@DATE@@: the current date.
+    - @@PAGESCNT@@: the total number of pages.
+    - @@PAGENUM@@: the current page number.
+    - @@TIME@@: the current time.
+    - @@TITLE@@: the title of the document, as passed to the wxRichTextPrinting or
      wxRichTextLayout constructor.

    @library{wxrichtext}
--- a/interface/wx/uilocale.h
+++ b/interface/wx/uilocale.h
@@ -340,7 +340,7 @@ public:
    /**
        Set language.

-        Return reference to @this for method chaining.
+        Return reference to `this` for method chaining.

        See https://www.loc.gov/standards/iso639-2/php/English_list.php for the
        list of all language codes.
@@ -353,7 +353,7 @@ public:

    /**
        Set region.
-        Return reference to @this for method chaining.
+        Return reference to `this` for method chaining.

        @param region
            It specifies an uppercase ISO 3166-1 country/region identifier.
@@ -365,7 +365,7 @@ public:

        Note that script value is currently ignored under Unix systems.

-        Return reference to @this for method chaining.
+        Return reference to `this` for method chaining.

        @param script
            It is an initial-uppercase ISO 15924 script code.
@@ -378,7 +378,7 @@ public:
        Note that this value is only used under Unix systems and simply ignored
        under the other ones.

-        Return reference to @this for method chaining.
+        Return reference to `this` for method chaining.

        @param charset
            Charset is a string such as "UTF-8", "ISO855915" or "KOI8R".
@@ -392,7 +392,7 @@ public:
        Note that this value is only used under Unix systems and simply ignored
        under the other ones.

-        Return reference to @this for method chaining.
+        Return reference to `this` for method chaining.

        @param modifier
            Modifier is defined by ISO/IEC 15897.
@@ -418,9 +418,9 @@ public:
    /**
        Construct platform dependent name.
        Format:
-        Windows: <language>-<script>-<REGION>
-        Unix:    <language>_<REGION>.<charset>@<modifier>
-        MacOS:   <language>-<script>_<REGION>
+        Windows: \<language\>-\<script\>-\<REGION\>
+        Unix:    \<language\>_\<REGION\>.\<charset\>@\<modifier\>
+        MacOS:   \<language\>-\<script\>_\<REGION\>
    */
    wxString GetName() const;