fix many doxygen warnings; added wxMotif section in platdetails (at the very least to fix warnings about missing page_port_wxmotif section) with its logo

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@55859 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/doxygen/Doxyfile_inc

@@ -221,7 +221,7 @@ FILE_VERSION_FILTER    =
 
 QUIET                  = YES
 WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 WARN_IF_DOC_ERROR      = YES
 WARN_NO_PARAMDOC       = YES
 WARN_FORMAT            = "$file:$line: $text   "

docs/doxygen/mainpages/const_wxusedef.h

@@ -33,7 +33,7 @@ using @if_ and not @ifdef_.
 
 <hr>
 
-@section page_wxusedef_multi Most important wxUSE symbols
+@section page_wxusedef_important Most important wxUSE symbols
 
 This table summarizes some of the global build features affecting the entire
 library:

docs/doxygen/mainpages/devtips.h

@@ -429,7 +429,7 @@ the end of the program if wxWidgets is suitably configured. Depending on the
 operating system and compiler, more or less specific information about the
 problem will be logged.
 
-You should also use @ref group_funcmacro_debugging as part of a "defensive
+You should also use @ref group_funcmacro_debug as part of a "defensive
 programming" strategy, scattering wxASSERT()s liberally to test for problems in
 your code as early as possible. Forward thinking will save a surprising amount
 of time in the long run.

docs/doxygen/mainpages/platdetails.h

@@ -24,6 +24,7 @@ and ports.
 @li @ref page_port_wxos2
 @li @ref page_port_wxmgl
 @li @ref page_port_wxx11
+@li @ref page_port_wxmotif
 @li @ref page_port_wxmsw
 @li @ref page_port_nativedocs
 
@@ -66,7 +67,7 @@ This is the default for many systems.
 GTK+ 1.2 can still be used, albeit discouraged. For that you can
 pass @c --with-gtk=1 to the @c configure script.
 
-For further information, please see the files in docs/gtk
+For further information, please see the files in @c docs/gtk
 in the distribution.
 
 
@@ -89,7 +90,7 @@ both architecture. Unfortunately, wxMac does not support any
 64-bit architecture since Apple decided not to port its Carbon
 API entirely to 64-bit.
 
-For further information, please see the files in docs/mac
+For further information, please see the files in @c docs/mac
 in the distribution.
 
 
@@ -102,12 +103,15 @@ in the distribution.
 @endhtmlonly
 
 wxCocoa is another port of wxWidgets for the Macintosh OS
-platform. But in contrat to wxMac, it uses the Cocoa API.
+platform. But in contrast to wxMac, it uses the Cocoa API.
 Much work has gone into this port and many controls are
 functional, but the port has not reached the maturity
 of the wxMac port yet. It should be possible to use wxCocoa
 on 64-bit architectures.
 
+For further information, please see the files in @c docs/mac
+in the distribution.
+
 
 @section page_port_wxmgl wxMGL
 
@@ -130,7 +134,7 @@ need to type:
 
 Under DOS, wxMGL uses a dmake based make system.
 
-For further information, please see the files in docs/mgl
+For further information, please see the files in @c docs/mgl
 in the distribution.
 
 
@@ -140,6 +144,9 @@ in the distribution.
 wxOS2 is a port of wxWidgets for the IBM OS/2 Warp3 and Warp4 platforms.
 This port is currently under construction and in beta phase.
 
+For further information, please see the files in @c docs/os2
+in the distribution.
+
 
 
 @section page_port_wxx11 wxX11
@@ -160,12 +167,26 @@ need to type:
 
 @verbatim configure --with-x11 --with-universal @endverbatim
 
-For further information, please see the files in docs/x11
+For further information, please see the files in @c docs/x11
 in the distribution. There is also a page on the use of
 wxWidgets for embedded applications on the wxWidgets web site.
 
 
 
+@section page_port_wxmotif wxMotif
+
+@htmlonly
+<img src="motif_logo.png" alt="Motif logo" title="Motif logo" class="logo">
+@endhtmlonly
+
+wxMotif is a port of wxWidgets for X11 systems using Motif libraries.
+Motif libraries provide a clean and fast user interface at the expense
+of the beauty and candy of newer interfaces like GTK.
+
+For further information, please see the files in @c docs/motif
+in the distribution.
+
+
 
 
 @section page_port_wxmsw wxMSW

docs/doxygen/overviews/xrc_format.h

@@ -6,6 +6,13 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+
+/*
+    NOTE: to make doxygen happy about <custom-tags> we're forced to
+          escape all < and > symbols which appear inside a doxygen comment
+*/
+
+
 /**
 
 @page xrc_format XRC file format
@@ -34,6 +41,9 @@ This document describes the format of XRC resource files, as used by
 wxXmlResource.
 
 
+<hr>
+
+
 @section xrc_format_overview Overview
 
 XRC file is a XML file with all of its elements in the
@@ -55,9 +65,9 @@ Child objects are not directly accessible via wxXmlResource, they can only
 be accessed using XRCCTRL().
 
 
-@section xrc_format_root Root element: <resource>
+@section xrc_format_root Root element: \<resource\>
 
-The root element is always @c <resource>. It has one optional attribute, @c
+The root element is always @c \<resource\>. It has one optional attribute, @c
 version. If set, it specifies version of the file. In absence of @c version
 attribute, the default is @c "0.0.0.0".
 
@@ -80,7 +90,7 @@ specified to take advantage of the latest capabilities:
 </resource>
 @endcode
 
-@c <resource> may have arbitrary number of
+@c \<resource\> may have arbitrary number of
 @ref xrc_format_objects "object elements" as its children; they are referred
 to as @em toplevel objects in the rest of this document. Unlike objects defined
 deeper in the hierarchy, toplevel objects @em must have their @c name attribute
@@ -90,9 +100,9 @@ set and it must be set to a value unique among root's children.
 
 @section xrc_format_objects Defining objects
 
-@subsection xrc_format_object <object>
+@subsection xrc_format_object \<object\>
 
-The @c <object> element represents a single object (typically a GUI element)
+The @c \<object\> element represents a single object (typically a GUI element)
 and it usually maps directly to a wxWidgets class instance. It has one
 mandatory attribute, @c class, and optional @c name and @c subclass attributes.
 
@@ -120,18 +130,18 @@ The @c subclass attribute optional name of class whose constructor will be
 called instead of the constructor for "class".
 See @ref xrc_format_extending_subclass for more details.
 
-@c <object> element may -- and almost always do -- have children elements.
+@c \<object\> element may -- and almost always do -- have children elements.
 These come in two varieties:
 
  -# Object's properties. A @em property is a value describing part of object's
     behaviour, for example the "label" property on wxButton defines its label.
     In the most common form, property is a single element with text content
-    ("<label>Cancel</label"), but they may use nested subelements too (e.g.
+    ("<label>Cancel</label>"), but they may use nested subelements too (e.g.
     @ref xrc_format_type_font "font property"). A property can only be
     listed once in an object's definition.
  -# Child objects. Window childs, sizers, sizer items or notebook pages
     are all examples of child objects. They are represented using nested
-    @c <object> elements and are can be repeated more than once. The specifics
+    @c \<object\> elements and are can be repeated more than once. The specifics
     of which object classes are allowed as children are class-specific and
     are documented below in @ref xrc_format_controls.
 
@@ -154,12 +164,12 @@ Example:
 
 @subsection xrc_format_object_ref <object_ref>
 
-Anywhere an @c <object> element can be used, @c <object_ref> may be used
+Anywhere an @c \<object\> element can be used, @c \<object_ref\> may be used
-instead. @c <object_ref> is a @em reference to another named (i.e. with the
+instead. @c \<object_ref\> is a @em reference to another named (i.e. with the
-@c name attribute) @c <object> element. It has one mandatory attribute,
+@c name attribute) @c \<object\> element. It has one mandatory attribute,
-@c ref, with value containing the name of a named @c <object> element. When an
+@c ref, with value containing the name of a named @c \<object\> element. When an
-@c <object_ref> is encountered, a copy of the referenced @c <object> element
+@c \<object_ref\> is encountered, a copy of the referenced @c \<object\> element
-is made in place of @c <object_ref> occurrence and processed as usual.
+is made in place of @c \<object_ref\> occurrence and processed as usual.
 
 For example, the following code:
 @code
@@ -179,16 +189,16 @@ is equivalent to
 @endcode
 
 Additionally, it is possible to override some parts of the referenced object
-in the @c <object_ref> pointing to it. This is useful for putting repetitive
+in the @c \<object_ref\> pointing to it. This is useful for putting repetitive
 parts of XRC definitions into a template that can be reused and customized in
 several places. The two parts are merged as follows:
 
  -# The referred object is used as the initial content.
- -# All attributes set on @c <object_ref> are added to it.
+ -# All attributes set on @c \<object_ref\> are added to it.
- -# All child elements of @c <object_ref> are scanned. If an element with
+ -# All child elements of @c \<object_ref\> are scanned. If an element with
     the same name (and, if specified, the @c name attribute too) is found
     in the referred object, they are recursively merged.
- -# Child elements in @c <object_ref> that do not have a match in the referred
+ -# Child elements in @c \<object_ref\> that do not have a match in the referred
     object are appended to the list of children of the resulting element by
     default. Optionally, they may have @c insert_at attribute with two possible
     values, "begin" or "end". When set to "begin", the element is prepended to
@@ -861,11 +871,11 @@ file with bitmap data.
 
 @subsection xrc_format_bitmap wxBitmap
 
-Bitmaps are stored in @c <object> element with class set to @c wxBitmap. Such
+Bitmaps are stored in @c \<object\> element with class set to @c wxBitmap. Such
 bitmaps can then be loaded using wxXmlResource::LoadBitmap(). The content of
 the element is exactly same as in the case of
 @ref xrc_format_type_bitmap "bitmap properties", except that toplevel
-@c <object> is used.
+@c \<object\> is used.
 
 For example, instead of:
 @code
@@ -920,7 +930,7 @@ this section in the order of increasing complexity.
 @subsection xrc_format_extending_subclass Subclassing
 
 The simplest way to add custom controls is to set the @c subclass attribute
-of @c <object> element:
+of @c \<object\> element:
 
 @code
 <object name="my_value" class="wxTextCtrl" subclass="MyTextCtrl">
@@ -994,7 +1004,7 @@ The only requirements on the class are that
  -# the class must derive from wxObject
  -# it must support wxWidget's pseudo-RTTI mechanism
 
-Child elements of @c <object> are handled by the custom handler and there are
+Child elements of @c \<object\> are handled by the custom handler and there are
 no limitations on them imposed by XRC format.
 
 This is the only mechanism that works for toplevel objects -- custom controls
@@ -1014,7 +1024,7 @@ number of XRC files and their dependencies (bitmaps, icons etc.).
 @section xrc_format_oldversions Older format versions
 
 This section describes differences in older revisions of XRC format (i.e.
-files with older values of @c version attribute of @c <resource>).
+files with older values of @c version attribute of @c \<resource\>).
 
 
 @subsection xrc_format_pre_v2530 Versions before 2.5.3.0