Fix kconfig_compiler doxygen formatting

 * Doxygen sections instead of markdown list items and HTML headers
 * More descriptive section titles
 * HTML Definition list instead of a wide HTML table for compiler options
 * HTML Definition list instead of a markdown item list for data types
 * Syntax highlighting for examples

1 files changed, 285 insertions, 264 deletions

diff --git a/src/kconfig_compiler/README.dox b/src/kconfig_compiler/README.dox
index bf72f3eb..90dd4597 100644
--- a/src/kconfig_compiler/README.dox
+++ b/src/kconfig_compiler/README.dox
@@ -10,7 +10,7 @@ configuration data.
 The generated C++ source code is output to a .h and a .cpp file, whose base
 name is the same as that of the .kcfgc file.
 
-<h2>XML description of the configuration options</h2>
+\section kcfg_format The .kcfg XML file format: description of the configuration skeleton
 
 The structure of the .kcfg file is described by its DTD kcfg.xsd.
 
@@ -41,24 +41,38 @@ by the QVariant with exception of the clearly binary types
 (e.g. Pixmap, Image...) which are not supported. Besides those basic
 types the following special types are supported:
 
-- Path  This is a string that is specially treated as a file-path.
-  In particular paths in the home directory are prefixed with $HOME in
-  when being stored in the configuration file.
-
-- Enum  This indicates an enumeration. The possible enum values and optional
-  enum name should be provided via the \<choices\> tag. Enum values are
-  accessed as integers by the application but stored as strings in the
-  configuration file. This makes it possible to add more values at a later
-  date without breaking compatibility.
-
-- IntList  This indicates a list of integers. This information is provided
-  to the application as QList<int>. Useful for storing QSplitter
-  geometries.
-
-- Color  isn't a special type but has special input. It is generated as QColor.
-  Any valid input to QColor(QString) can be used (hex or SVG keyword notation)
-  as well as a special format r,g,b,a where the a denotes the alpha channel and
-  may be omitted.
+<dl>
+  <dt>Path</dt>
+  <dd>
+    This is a string that is specially treated as a file-path.
+    In particular paths in the home directory are prefixed with $HOME in
+    when being stored in the configuration file.
+  </dd>
+
+  <dt>Enum</dt>
+  <dd>
+    This indicates an enumeration. The possible enum values and optional
+    enum name should be provided via the \<choices\> tag. Enum values are
+    accessed as integers by the application but stored as strings in the
+    configuration file. This makes it possible to add more values at a later
+    date without breaking compatibility.
+  </dd>
+
+  <dt>IntList</dt>
+  <dd>
+    This indicates a list of integers. This information is provided
+    to the application as QList<int>. Useful for storing QSplitter
+    geometries.
+  </dd>
+
+  <dt>Color</dt>
+  <dd>
+    Isn't a special type but has special input. It is generated as QColor.
+    Any valid input to QColor(QString) can be used (hex or SVG keyword notation)
+    as well as a special format r,g,b,a where the a denotes the alpha channel and
+    may be omitted.
+  </dd>
+</dl>
 
 An entry can optionally have a default value which is used as default when
 the value isn't specified in any config file. Default values are interpreted
@@ -75,7 +89,7 @@ entry definition via the \<code\> tag. The contents of the \<code\> tag is
 inserted as-is. A typical use for this is to compute a common default value
 which can then be referenced by multiple entries that follow.
 
-<h2>Code generation options</h2>
+\section kcfgc_format The .kcfgc file format: code generation options
 
 The options for generating the C++ sources are read from the file with the
 extension .kcfgc. To generate a class add the corresponding kcfgc file to the
@@ -83,185 +97,189 @@ SOURCES line in the Makefile.am.
 
 The following options are read from the kcfgc file:
 
-<table>
-<tr>
-  <td><b><i>Name</i></b></td>
-  <td><b><i>Type</i></b></td>
-  <td><b><i>Default</i></b></td>
-  <td><b><i>Description</i></b></td>
-</tr>
-<tr>
-  <td><b>File</b></td>
-  <td>string</td>
-  <td>programname.kcfg</td>
-  <td>Name of kcfg file containing the options the class is generated for</td>
-</tr>
-<tr>
-  <td><b>HeaderExtension</b></td>
-  <td>string</td>
-  <td>h</td>
-  <td>Extension to use for the name of the generated C++ header files. Since KF 5.57</td>
-</tr>
-<tr>
-  <td><b>SourceExtension</b></td>
-  <td>string</td>
-  <td>cpp</td>
-  <td>Extension to use for the name of the generated C++ source file. Since KF 5.57</td>
-</tr>
-<tr>
-  <td><b>NameSpace</b></td>
-  <td>string</td>
-  <td>-</td>
-  <td>Optional namespace for generated class</td>
-</tr>
-<tr>
-  <td><b>ClassName</b></td>
-  <td>string</td>
-  <td>-</td>
-  <td>Name of generated class (required)</td>
-</tr>
-<tr>
-  <td><b>Inherits</b></td>
-  <td>string</td>
-  <td>KConfigSkeleton</td>
-  <td>Class the generated class inherits from. This class must inherit
-  KConfigSkeleton and must provide a default constructor (kcfgfile not specified), a constructor
-  taking a QString argument (kcfgfile with "name" attribute) and a constructor taking a
-  KSharedConfig::Ptr as argument (kcfgfile with "arg" attribute).
-  Please refer to the documentation of KConfigSkeleton.
-  </td>
-</tr>
-<tr>
-  <td><b>Visibility</b></td>
-  <td>string</td>
-  <td>-</td>
-  <td>Inserts visibility directive (for example KDE_EXPORT) between "class" keyword and class
-  name in header file</td>
-</tr>
-<tr>
-  <td><b>Singleton</b></td>
-  <td>bool</td>
-  <td>false</td>
-  <td>Generated class is a singleton.</td>
-</tr>
-<tr>
-  <td><b>CustomAdditions</b></td>
-  <td>bool</td>
-  <td>-</td>
-  <td></td>
-</tr>
-<tr>
-  <td><b>MemberVariables</b></td>
-  <td>string: public|protected|private|dpointer</td>
-  <td>private</td>
-  <td>C++ access modifier used for member variables holding the configuration
-  values</td>
-</tr>
-<tr>
-  <td><b>IncludeFiles</b></td>
-  <td>comma separated list of strings</td>
-  <td>-</td>
-  <td>Names of files to be included in the header of the generated class. Enclose a
-  file name in (escaped) double quotes to generate \#include "..." instead of
-  \#include \<...\>.</td>
-</tr>
-<tr>
-  <td><b>SourceIncludeFiles</b></td>
-  <td>comma separated list of strings</td>
-  <td>-</td>
-  <td>Names of files to be included in the source file of the generated class. Enclose
-  a file name in (escaped) double quotes to generate \#include "..." instead of
-  \#include \<...\>.</td>
-</tr>
-<tr>
-  <td><b>Mutators</b></td>
-  <td>true, false or a comma separated list of options</td>
-  <td>false</td>
-  <td>If true, mutator functions for all configuration options are generated.
-      If false, no mutator functions are generated. If a list is provided,
-      mutator functions are generated for the options that are listed.</td>
-</tr>
-<tr>
-  <td><b>Notifiers</b></td>
-  <td>true, false or a comma separated list of options</td>
-  <td>false</td>
-  <td>If true, entries will be written with the <b>Notify</b> flag enabled,
-      so changes can be detected using <b>KConfigWatcher</b>.
-      If a list is provided, the options that are listed are written with
-      said flag.</td>
-</tr>
-<tr>
-  <td><b>DefaultValueGetters</b></td>
-  <td>true, false or a comma separated list of options</td>
-  <td>false</td>
-  <td>If true, functions to return the default value of all configuration options
-      are generated. If false, no default value functions are generated. If a list
-      is provided, default value functions are generated for the options that are listed.</td>
-</tr>
-<tr>
-  <td><b>ItemAccessors</b></td>
-  <td>bool</td>
-  <td>false</td>
-  <td>Generate accessor functions for the KConfigSkeletonItem objects
-  corresponding to the configuration options. If <b>SetUserTexts</b> is set,
-  <b>ItemAccessors</b> also has to be set.</td>
-</tr>
-<tr>
-  <td><b>SetUserTexts</b></td>
-  <td>bool</td>
-  <td>false</td>
-  <td>Set the label and whatthis texts of the items from the kcfg file.If
-  <b>SetUserTexts</b> is set, <b>ItemAccessors</b> also has to be set.</td>
-</tr>
-<tr>
-  <td><b>GlobalEnums</b></td>
-  <td>bool</td>
-  <td>false</td>
-  <td>If set to true all choices of Enum items will be created in the global
-  scope of the generated class. If set to false, each Enum item whose enum is not
-  explicitly named will get its own namespace for its choices.</td>
-</tr>
-<tr>
-  <td><b>UseEnumTypes</b></td>
-  <td>bool</td>
-  <td>false</td>
-  <td>If set to true, all Enum items whose enums are named will use enum types for
-  the return value of accessor functions and for the parameter of mutator
-  functions. This eliminates the need to cast accessor return values to the enum
-  type if you want to use the enum type in your own code. If set to false,
-  accessor return values and mutator parameters will be of type int.</td>
-</tr>
-<tr>
-  <td><b>ForceStringFilename</b></td>
-  <td>bool</td>
-  <td>false</td>
-  <td>If set to true, forces the first parameter of the generated class to be a QString when using an argument for the filename. This is useful to specify at runtime the filename of the configuration class.</td>
-</tr>
-<tr>
-  <td><b>GenerateProperties</b></td>
-  <td>bool</td>
-  <td>false</td>
-  <td>If set to true, a Q_PROPERTY will be generated for each member variable holding a configuration value
-  and the Q_OBJECT macro will be added to the generated class.
-  Note that you will also need to pass the GENERATE_MOC option to the kconfig_add_kcfg_files macro.</td>
-</tr>
-<tr>
-  <td><b>ParentInConstructor</b></td>
-  <td>bool</td>
-  <td>false</td>
-  <td>If set to true, the generated constructor will take an additional QObject* parameter that will be used as the object's parent.
-  This is useful when working with KQuickAddons::ManagedConfigModule to set it as the parent of the generated class to allow automatic settings discovery and handle the deallocation.
-  Note this parameter is incompatible with <b>Singleton</b> set to true.
-  </td>
-</tr>
-</table>
-
-
-<h2>Advanced options</h2>
+
+<dl>
+  <dt>File=\<string\></dt>
+  <dd>
+    Default: \<programname\>.kcfg \n
+    Name of kcfg file containing the options the class is generated for
+    <!-- what? -->
+  </dd>
+
+  <dt>HeaderExtension=\<string\></dt>
+  <dd>
+    Default: h \n
+    Since KF 5.57 \n
+    Extension to use for the name of the generated C++ header files.
+  </dd>
+
+  <dt>SourceExtension=\<string\></dt>
+  <dd>
+    Default: cpp \n
+    Since KF 5.57 \n
+    Extension to use for the name of the generated C++ source file.
+  </dd>
+
+  <dt>NameSpace=\<string\></dt>
+  <dd>
+    Optional namespace for generated class
+  </dd>
+
+  <dt>ClassName=\<string\></dt>
+  <dd>
+    Name of generated class (required)
+  </dd>
+
+  <dt>Inherits=\<string\></dt>
+  <dd>
+    Default: KConfigSkeleton \n
+    Class the generated class inherits from.
+
+    This class must inherit KConfigSkeleton and must provide a default
+    constructor (kcfgfile not specified), a constructor taking a
+    QString argument (kcfgfile with "name" attribute) and a constructor
+    taking a KSharedConfig::Ptr as argument (kcfgfile with "arg" attribute).
+    Please refer to the documentation of KConfigSkeleton.
+  </dd>
+
+  <dt>Visibility=\<string\></dt>
+  <dd>
+    Inserts visibility directive (for example KDE_EXPORT) between
+    "class" keyword and class name in header file
+  </dd>
+
+  <dt>Singleton=\<bool\></dt>
+  <dd>
+    Default: false \n
+    Generated class is a singleton.
+  </dd>
+
+  <dt>CustomAdditions=\<bool\></dt>
+  <dd>
+    <!-- what? -->
+  </dd>
+
+  <dt>MemberVariables=\<string\></dt>
+  <dd>
+    Values: public, protected, private, dpointer \n
+    Default: private \n
+    C++ access modifier used for member variables holding the configuration
+    values
+  </dd>
+
+  <dt>IncludeFiles=\<string\>, \<string\> ...</dt>
+  <dd>
+    Names of files to be included in the header of the generated class.
+
+    Enclose a file name in (escaped) double quotes to generate
+    \#include "..." instead of \#include \<...\>.
+  </dd>
+
+  <dt>SourceIncludeFiles=\<string\>, \<string\> ...</dt>
+  <dd>
+    Names of files to be included in the source file of the generated class.
+
+    Enclose a file name in (escaped) double quotes to generate
+    \#include "..." instead of \#include \<...\>.
+  </dd>
+
+  <dt>Mutators=\<value\></dt>
+  <dd>
+    Values: true, false or a comma separated list of options \n
+    Default: false \n
+    If true, mutator functions for all configuration options are generated.
+    If false, no mutator functions are generated. If a list is provided,
+    mutator functions are generated for the options that are listed.
+  </dd>
+
+  <dt>Notifiers=\<value\></dt>
+  <dd>
+    Values: true, false or a comma separated list of options \n
+    Default: false \n
+    If true, entries will be written with the <b>Notify</b> flag enabled,
+    so changes can be detected using <b>KConfigWatcher</b>.
+    If a list is provided, the options that are listed are written with
+    said flag.
+  </dd>
+
+  <dt>DefaultValueGetters=\<value\></dt>
+  <dd>
+    Values: true, false or a comma separated list of options \n
+    Default: false \n
+    If true, functions to return the default value of all configuration options
+    are generated. If false, no default value functions are generated. If a list
+    is provided, default value functions are generated for the options that are listed.
+  </dd>
+
+  <dt>ItemAccessors=\<bool\></dt>
+  <dd>
+    Default: false \n
+    Generate accessor functions for the KConfigSkeletonItem objects
+    corresponding to the configuration options. If <b>SetUserTexts</b> is set,
+    <b>ItemAccessors</b> also has to be set.
+  </dd>
+
+  <dt>SetUserTexts=\<bool\></dt>
+  <dd>
+    Default: false \n
+    Set the label and whatthis texts of the items from the kcfg file.
+    If <b>SetUserTexts</b> is set, <b>ItemAccessors</b> also has to be set.
+  </dd>
+
+  <dt>GlobalEnums=\<bool\></dt>
+  <dd>
+    Default: false \n
+    If set to true all choices of Enum items will be created in the global
+    scope of the generated class. If set to false, each Enum item whose enum is not
+    explicitly named will get its own namespace for its choices.
+  </dd>
+
+  <dt>UseEnumTypes=\<bool\></dt>
+  <dd>
+    Default: false \n
+    If set to true, all Enum items whose enums are named will use enum types for
+    the return value of accessor functions and for the parameter of mutator
+    functions. This eliminates the need to cast accessor return values to the enum
+    type if you want to use the enum type in your own code. If set to false,
+    accessor return values and mutator parameters will be of type int.
+  </dd>
+
+  <dt>ForceStringFilename=\<bool\></dt>
+  <dd>
+    Default: false \n
+    If set to true, forces the first parameter of the generated class
+    to be a QString when using an argument for the filename.
+    This is useful to specify at runtime the filename of the configuration class.
+  </dd>
+
+  <dt>GenerateProperties=\<bool\></dt>
+  <dd>
+    Default: false \n
+    If set to true, a Q_PROPERTY will be generated for each member variable holding a
+    configuration value and the Q_OBJECT macro will be added to the generated class.
+    Note that you will also need to pass the GENERATE_MOC option to the
+    kconfig_add_kcfg_files macro.
+  </dd>
+
+
+  <dt>ParentInConstructor=\<bool\></dt>
+  <dd>
+    Default: false \n
+    If set to true, the generated constructor will take an additional QObject*
+    parameter that will be used as the object's parent.
+    This is useful when working with KQuickAddons::ManagedConfigModule
+    to set it as the parent of the generated class to allow automatic
+    settings discovery and handle the deallocation.
+    Note this parameter is incompatible with <b>Singleton</b> set to true.
+  </dd>
+</dl>
+
+
+\section entry_options Advanced entry options
 
 There are several possibilities to parameterize entries.
 
-- Parameterized entries
+\subsection parametrized_entries Parameterized entries
 
 An entry can be parameterized using a fixed range parameter specified with
 the \<parameter\> tag. Such parameter can either be an Enum or an int. An Enum
@@ -284,15 +302,15 @@ param attribute is specified the default value only applies to that
 particular parameter value.
 
 Example 1:
-\verbatim
-  <entry name="Color$(ColorIndex)" type="Color" key="color_$(ColorIndex)">
-    <parameter name="ColorIndex" type="Int" max="3"/>
-    <default param="0">#ff0000</default>
-    <default param="1">#00ff00</default>
-    <default param="2">#0000ff</default>
-    <default param="3">#ffff00</default>
-  </entry>
-\endverbatim
+\code{.xml}
+<entry name="Color$(ColorIndex)" type="Color" key="color_$(ColorIndex)">
+  <parameter name="ColorIndex" type="Int" max="3"/>
+  <default param="0">#ff0000</default>
+  <default param="1">#00ff00</default>
+  <default param="2">#0000ff</default>
+  <default param="3">#ffff00</default>
+</entry>
+\endcode
 
 The above describes 4 color configuration entries with the following defaults:
 
@@ -308,75 +326,77 @@ a QColor color(int ColorIndex) and a
 void setColor(int ColorIndex, const QColor &v) function.
 
 Example 2:
-\verbatim
-  <entry name="Sound$(SoundEvent)" type="String" key="sound_$(SoundEvent)">
-    <parameter name="SoundEvent" type="Enum">
-      <values>
-        <value>Explosion</value>
-        <value>Crash</value>
-        <value>Missile</value>
-      </values>
-    </parameter>
-    <default param="Explosion">boom.wav</default>
-    <default param="Crash">crash.wav</default>
-    <default param="Missile">missile.wav</default>
-  </entry>
-\endverbatim
+\code{.xml}
+<entry name="Sound$(SoundEvent)" type="String" key="sound_$(SoundEvent)">
+  <parameter name="SoundEvent" type="Enum">
+    <values>
+      <value>Explosion</value>
+      <value>Crash</value>
+      <value>Missile</value>
+    </values>
+  </parameter>
+  <default param="Explosion">boom.wav</default>
+  <default param="Crash">crash.wav</default>
+  <default param="Missile">missile.wav</default>
+</entry>
+\endcode
 
 The above describes 3 string configuration entries with the following defaults:
 
+\verbatim
 sound_Explosion=boom.wav
 sound_Crash=crash.wav
 sound_Missile=missile.wav
+\endverbatim
 
 The configuration options will be accessible to the application via
 a QString sound(int SoundEvent) and a
 void setSound(int SoundEvent, const QString &v) function.
 
-- Parameterized groups
+\subsection parametrized_groups Parameterized groups
 
 A group name can be parametrized using a parameter given to the KConfigSkeleton
 instance (which means this feature cannot be used with singleton classes).
 
 Example 1:
-\verbatim
-  <kcfgfile name="testrc">
-    <parameter name="groupname"/>
-  </kcfgfile>
-  <group name="$(groupname)">
-    <entry key="Text" type="string">
-    </entry>
-  </group>
-\endverbatim
+\code{.xml}
+<kcfgfile name="testrc">
+  <parameter name="groupname"/>
+</kcfgfile>
+<group name="$(groupname)">
+  <entry key="Text" type="string">
+  </entry>
+</group>
+\endcode
 
 In this case passing "Group2" as the 'groupname' parameter to the generated class
 will make it use group "Group2" for the entry "Text".
 
-- Enums
+\subsection enums Enums
 
 By default, if <b>GlobalEnums</b> is set to false, a separate named enum will be generated
 for each Enum entry. Since each enum is defined in a little enclosing class of its own,
 this allows the same Enum value names to be used in different enums. For example, the
 .kcfg entry
 
-\verbatim
+\code{.xml}
 <entry name="KeepData" type="Enum">
   <choices>
     <choice name="Do">
     <choice name="Dont" value="Don't">
   </choices>
 </entry>
-\endverbatim
+\endcode
 
 will generate this public class containing the enum definition, inside the generated class:
 
-\verbatim
-    class EnumKeepData
-    {
-      public:
-      enum type { Do, Dont, COUNT };
-    };
-\endverbatim
+\code{.cpp}
+class EnumKeepData
+{
+  public:
+  enum type { Do, Dont, COUNT };
+};
+\endcode
 
 Since 5.68, if present the <b>value</b> attribute will be used as the choice value written to the backend
 instead of the <b>name</b>, allowing to write text incompatible with enum naming.
@@ -388,21 +408,21 @@ in \<choices\> to prevent duplicate enum member names clashing. Using this, the
 names are prefixed in code with the string you specify. For example, if <b>GlobalEnums</b>
 is set to true, the .kcfg entry
 
-\verbatim
+\code{.xml}
 <entry name="KeepData" type="Enum">
   <choices prefix="Keep_">
     <choice name="Do">
     <choice name="Dont" value="Don't">
   </choices>
 </entry>
-\endverbatim
+\endcode
 
 will generate config file entries of "KeepData=Do" and "KeepData=Dont", but the enum
 will be declared
 
-\verbatim
-    enum { Keep_Do, Keep_Dont };
-\endverbatim
+\code{.cpp}
+enum { Keep_Do, Keep_Dont };
+\endcode
 
 It is possible to specify your own name for a generated enum, by including a
 'name' parameter in \<choices\>. Just like unnamed enums, this enum will be defined in
@@ -412,20 +432,20 @@ Therefore the names of Enum values must be unique across both unnamed enums (if
 
 An example of a specifically named enum:
 
-\verbatim
+\code{.xml}
 <entry name="KeepData" type="Enum">
   <choices name="Types">
     <choice name="Do">
     <choice name="Dont">
   </choices>
 </entry>
-\endverbatim
+\endcode
 
 which results in the following enum declaration, inside the generated class:
 
-\verbatim
-    enum Types { Do, Dont };
-\endverbatim
+\code{.cpp}
+enum Types { Do, Dont };
+\endcode
 
 It is also possible to specify the use of enums external to the generated class, by
 including the string "::" in the enum name - just ensure that it is sufficiently
@@ -433,31 +453,32 @@ qualified to be unambiguous in use. To specify use of an unnamed enum, append a
 trailing "::". For example, to use the enum 'myEnum' defined in class ClassA, use
 either of
 
-\verbatim
+\code{.xml}
 <choices name="ClassA::myEnum">
 <choices name="::ClassA::myEnum">
-\endverbatim
+\endcode
 
 To specify an unnamed enum in namespace ProgSpace, use
 
-\verbatim
+\code{.xml}
 <choices name="ProgSpace::">
-\endverbatim
+\endcode
 
 To specify a top-level unnamed enum, use
 
-\verbatim
+\code{.xml}
 <choices name="::">
-\endverbatim
+\endcode
 
 To specify the top-level enum 'anotherEnum', use
 
-\verbatim
+\code{.xml}
+
 <choices name="::anotherEnum">
-\endverbatim
+\endcode
 
 
-- Signal support.
+\subsection notify_signals Notify signals
 
 An entry can emit a signal when it gets changed. First of all, you must
 define a list of signals for the configuration class. The signal's name may be
@@ -468,26 +489,26 @@ of the entries defined in the .kcfg file.
 A signal definition can also contain a \<label\> tag which will be
 the documentation line in the generated file.
 
-\verbatim
+\code{.xml}
 <signal name="emoticonSettingsChanged" />
 
 <signal name="styleChanged">
   <label>Tell when a complete style change.</label>
-    <argument type="String">stylePath</argument>
-    <argument type="String">StyleCSSVariant</argument>
+  <argument type="String">stylePath</argument>
+  <argument type="String">StyleCSSVariant</argument>
 </signal>
-\endverbatim
+\endcode
 
 After defining the signals, you must tell which signal to emit for the entry.
 A signal can be emitted by multiple entries. Also, you don't need to specify the arguments
 for a signal, the signal name will suffice.
 
-\verbatim
+\code{.xml}
 <entry key="stylePath" type="String">
   <label>Absolute path to a directory containing a Adium/Kopete chat window style.</label>
   <emit signal="styleChanged" />
 </entry>
-\endverbatim
+\endcode
 
 You can also use the generic configChanged() signal from KConfigSkeleton to notify your application
 about configuration changes.