From 5d0dac047384e1f46e2de57f9b9ebf4f6fde0e26 Mon Sep 17 00:00:00 2001 From: David Hurka Date: Thu, 4 Feb 2021 12:15:48 +0000 Subject: 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 --- src/kconfig_compiler/README.dox | 549 +++++++++++++++++++++------------------- 1 file changed, 285 insertions(+), 264 deletions(-) (limited to 'src') 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. -

XML description of the configuration options

+\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 \ 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. 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. +
+
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 \ 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. 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. +
+
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 \ tag. The contents of the \ 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. -

Code generation options

+\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: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDescription
Filestringprogramname.kcfgName of kcfg file containing the options the class is generated for
HeaderExtensionstringhExtension to use for the name of the generated C++ header files. Since KF 5.57
SourceExtensionstringcppExtension to use for the name of the generated C++ source file. Since KF 5.57
NameSpacestring-Optional namespace for generated class
ClassNamestring-Name of generated class (required)
InheritsstringKConfigSkeletonClass 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. -
Visibilitystring-Inserts visibility directive (for example KDE_EXPORT) between "class" keyword and class - name in header file
SingletonboolfalseGenerated class is a singleton.
CustomAdditionsbool-
MemberVariablesstring: public|protected|private|dpointerprivateC++ access modifier used for member variables holding the configuration - values
IncludeFilescomma separated list of strings-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 \<...\>.
SourceIncludeFilescomma separated list of strings-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 \<...\>.
Mutatorstrue, false or a comma separated list of optionsfalseIf 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.
Notifierstrue, false or a comma separated list of optionsfalseIf true, entries will be written with the Notify flag enabled, - so changes can be detected using KConfigWatcher. - If a list is provided, the options that are listed are written with - said flag.
DefaultValueGetterstrue, false or a comma separated list of optionsfalseIf 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.
ItemAccessorsboolfalseGenerate accessor functions for the KConfigSkeletonItem objects - corresponding to the configuration options. If SetUserTexts is set, - ItemAccessors also has to be set.
SetUserTextsboolfalseSet the label and whatthis texts of the items from the kcfg file.If - SetUserTexts is set, ItemAccessors also has to be set.
GlobalEnumsboolfalseIf 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.
UseEnumTypesboolfalseIf 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.
ForceStringFilenameboolfalseIf 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.
GeneratePropertiesboolfalseIf 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.
ParentInConstructorboolfalseIf 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 Singleton set to true. -
- - -

Advanced options

+ +
+
File=\
+
+ Default: \.kcfg \n + Name of kcfg file containing the options the class is generated for + +
+ +
HeaderExtension=\
+
+ Default: h \n + Since KF 5.57 \n + Extension to use for the name of the generated C++ header files. +
+ +
SourceExtension=\
+
+ Default: cpp \n + Since KF 5.57 \n + Extension to use for the name of the generated C++ source file. +
+ +
NameSpace=\
+
+ Optional namespace for generated class +
+ +
ClassName=\
+
+ Name of generated class (required) +
+ +
Inherits=\
+
+ 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. +
+ +
Visibility=\
+
+ Inserts visibility directive (for example KDE_EXPORT) between + "class" keyword and class name in header file +
+ +
Singleton=\
+
+ Default: false \n + Generated class is a singleton. +
+ +
CustomAdditions=\
+
+ +
+ +
MemberVariables=\
+
+ Values: public, protected, private, dpointer \n + Default: private \n + C++ access modifier used for member variables holding the configuration + values +
+ +
IncludeFiles=\, \ ...
+
+ 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 \<...\>. +
+ +
SourceIncludeFiles=\, \ ...
+
+ 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 \<...\>. +
+ +
Mutators=\
+
+ 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. +
+ +
Notifiers=\
+
+ Values: true, false or a comma separated list of options \n + Default: false \n + If true, entries will be written with the Notify flag enabled, + so changes can be detected using KConfigWatcher. + If a list is provided, the options that are listed are written with + said flag. +
+ +
DefaultValueGetters=\
+
+ 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. +
+ +
ItemAccessors=\
+
+ Default: false \n + Generate accessor functions for the KConfigSkeletonItem objects + corresponding to the configuration options. If SetUserTexts is set, + ItemAccessors also has to be set. +
+ +
SetUserTexts=\
+
+ Default: false \n + Set the label and whatthis texts of the items from the kcfg file. + If SetUserTexts is set, ItemAccessors also has to be set. +
+ +
GlobalEnums=\
+
+ 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. +
+ +
UseEnumTypes=\
+
+ 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. +
+ +
ForceStringFilename=\
+
+ 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. +
+ +
GenerateProperties=\
+
+ 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. +
+ + +
ParentInConstructor=\
+
+ 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 Singleton set to true. +
+
+ + +\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 \ 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 - - - #ff0000 - #00ff00 - #0000ff - #ffff00 - -\endverbatim +\code{.xml} + + + #ff0000 + #00ff00 + #0000ff + #ffff00 + +\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 - - - - Explosion - Crash - Missile - - - boom.wav - crash.wav - missile.wav - -\endverbatim +\code{.xml} + + + + Explosion + Crash + Missile + + + boom.wav + crash.wav + missile.wav + +\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 - - - - - - - -\endverbatim +\code{.xml} + + + + + + + +\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 GlobalEnums 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} -\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 value attribute will be used as the choice value written to the backend instead of the name, allowing to write text incompatible with enum naming. @@ -388,21 +408,21 @@ in \ to prevent duplicate enum member names clashing. Using this, the names are prefixed in code with the string you specify. For example, if GlobalEnums is set to true, the .kcfg entry -\verbatim +\code{.xml} -\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 \. 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} -\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} -\endverbatim +\endcode To specify an unnamed enum in namespace ProgSpace, use -\verbatim +\code{.xml} -\endverbatim +\endcode To specify a top-level unnamed enum, use -\verbatim +\code{.xml} -\endverbatim +\endcode To specify the top-level enum 'anotherEnum', use -\verbatim +\code{.xml} + -\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 \ tag which will be the documentation line in the generated file. -\verbatim +\code{.xml} - stylePath - StyleCSSVariant + stylePath + StyleCSSVariant -\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} -\endverbatim +\endcode You can also use the generic configChanged() signal from KConfigSkeleton to notify your application about configuration changes. -- cgit v1.2.1