[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-devel
Subject: [patch] updates for kdelibs apidox
From: Brad Hards <bhards () bigpond ! net ! au>
Date: 2003-11-02 20:06:01
[Download RAW message or body]
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Is it still OK to commit apidox fixes, such as the ones below.
- --
http://lca2004.linux.org.au - I'm registered. Are you?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)
iD8DBQE/pWOxGwwszQ/PZzgRAnmyAJ4oELQkXDYBQlkpZTDXFXSEsFL+pgCgpoCX
2+lKsX9W3mPUXNnfmUZAKzs=
=Wl7d
-----END PGP SIGNATURE-----
["kdecore-apidox-2003-11-03.patch" (text/x-diff)]
? Doxyfile
? kdecore-apidox-2003-11-03.patch
Index: kcmdlineargs.h
===================================================================
RCS file: /home/kde/kdelibs/kdecore/kcmdlineargs.h,v
retrieving revision 1.55
diff -u -4 -p -r1.55 kcmdlineargs.h
--- kcmdlineargs.h 10 Oct 2003 12:49:55 -0000 1.55
+++ kcmdlineargs.h 2 Nov 2003 20:04:31 -0000
@@ -30,10 +30,13 @@ typedef QValueList<QCString> QCStringLis
/**
* @short Structure that holds command line options.
*
- * @see KCmdLineArgs
- * @see KCmdLineArgs::addCmdLineOptions()
+ * This class is intended to be used with the KCmdLineArgs class, which
+ * provides convenient and powerful command line argument parsing and
+ * handling functionality.
+ *
+ * @see KCmdLineArgs for additional usage information
*/
struct KCmdLineOptions
{
/**
@@ -55,9 +58,10 @@ struct KCmdLineOptions
* <i>myapp --help</i>. This value should be wrapped with I18N_NOOP().
*/
const char *description;
/**
- * The default value (if it is not specified on the command line).
+ * The default value for the option, if it is not specified on the
+ * command line.
*/
const char *def; // Default
};
@@ -71,17 +75,18 @@ class KCmdLineParsedArgs;
class KAboutData;
class KCmdLineArgsPrivate;
/**
- * Simple access to the command-line arguments.
+ * @short A class for command-line argument handling.
*
- * It takes into account Qt-specific options, KDE-specific options
- * and application specific options.
+ * KCmdLineArgs provides simple access to the command-line arguments
+ * for an application. It takes into account Qt-specific options,
+ * KDE-specific options and application specific options.
*
- * This class is used in main() via the static method
+ * This class is used in %main() via the static method
* init().
*
- * A typical KDE application should look like this:
+ * A typical %KDE application using %KCmdLineArgs should look like this:
*
* \code
* int main(int argc, char *argv[])
* {
@@ -100,11 +105,11 @@ class KCmdLineArgsPrivate;
* KUniqueApplication app;
*
* ....
*
- * // Handle our own options/argments
+ * // Handle our own options/arguments
* // A KApplication will usually do this in main but this is not
- * // necassery.
+ * // necessary.
* // A KUniqueApplication might want to handle it in newInstance().
*
* KCmdLineArgs *args = KCmdLineArgs::parsedArgs();
*
@@ -129,9 +134,10 @@ class KCmdLineArgsPrivate;
* ....
* }
* \endcode
*
- * options are defined as follow
+ * The options that an application supports are configured using the
+ * KCmdLineOptions class. An example is shown below:
*
* \code
* static const KCmdLineOptions options[] =
* {
@@ -141,16 +147,16 @@ class KCmdLineArgsPrivate;
* { "option1", I18N_NOOP("A long binary option, off by default."), 0 },
* { "nooption2", I18N_NOOP("A long binary option, on by default."), 0 },
* { ":", I18N_NOOP("Extra options:"), 0 },
* { "option3 \<file>", I18N_NOOP("A long option which takes an argument."), 0 \
},
- * { "option3 \<speed>", I18N_NOOP("As above with 9600 as default."), "9600" },
+ * { "option4 \<speed>", I18N_NOOP("A long option which takes an argument, \
defaulting to 9600."), "9600" },
* { "d", 0, 0 },
- * { "option4", I18N_NOOP("A long option which has a short option as alias."), 0 \
}, + * { "option5", I18N_NOOP("A long option which has a short option as \
alias."), 0 },
* { "e", 0, 0 },
- * { "nooption5", I18N_NOOP("Another long option with an alias."), 0 },
+ * { "nooption6", I18N_NOOP("Another long option with an alias."), 0 },
* { "f", 0, 0 },
- * { "option6 \<speed>", I18N_NOOP("'--option6 speed' is same a '-f speed'"), 0 \
},
- * { "!option7 \<cmd>", I18N_NOOP("All options following this one will be \
treated as arguments", 0 }, + * { "option7 \<speed>", I18N_NOOP("'--option7 \
speed' is the same as '-f speed'"), 0 }, + * { "!option8 \<cmd>", I18N_NOOP("All \
options following this one will be treated as arguments", 0 },
* { "+file", I18N_NOOP("A required argument 'file'.), 0 },
* { "+[arg1]", I18N_NOOP("An optional argument 'arg1'."), 0 },
* { "!+command", I18N_NOOP("A required argument 'command', that can contain \
multiple words, even starting with '-'.), 0 },
* { "", I18N_NOOP("Additional help text not associated with any particular \
option.") 0 }, @@ -164,10 +170,10 @@ class KCmdLineArgsPrivate;
* structure and can't do translations at compile time.
*
* Note that a program should define the options before any arguments.
*
- * When a long option has a short option as alias. A program should
- * only check for the long option.
+ * When a long option has a short option as an alias, a program should
+ * only test for the long option.
*
* With the above options a command line could look like:
* \code
* myapp -a -c 4800 --display localhost:0.0 --nooption5 -d /tmp/file
@@ -183,9 +189,9 @@ class KCmdLineArgsPrivate;
* \code
* myapp --nooption4
* \endcode
*
- * Normally if an option value is provided multiple times only the last
+ * If an option value is provided multiple times, normally only the last
* value is used:
* \code
* myapp -c 1200 -c 2400 -c 4800
* \endcode
@@ -194,23 +200,23 @@ class KCmdLineArgsPrivate;
* myapp -c 4800
* \endcode
*
* However, an application can choose to use all values specified as well.
- * E.g. to specify a number of directories to use:
+ * As an example of this, consider that you may wish to specify a
+ * number of directories to use:
* \code
* myapp -I /usr/include -I /opt/kde/include -I /usr/X11/include
* \endcode
* When an application does this it should mention this in the description
- * of the option. getOptionList()
+ * of the option. To access these options, use getOptionList()
*
* Tips for end-users:
*
* @li Single char options like "-a -b -c" may be combined into "-abc"
* @li The option "--foo bar" may also be written "--foo=bar"
* @li The option "-P lp1" may also be written "-P=lp1" or "-Plp1"
* @li The option "--foo bar" may also be written "-foo bar"
*
- * @short A class for command-line argument handling.
* @author Waldo Bastian
* @version 0.0.4
*/
class KCmdLineArgs
@@ -229,19 +235,24 @@ public:
* @param _argc As passed to @p main(...).
* @param _argv As passed to @p main(...).
* @param _appname The untranslated name of your application. This should
* match with @p argv[0].
- * @param programName A displayable program name string. This string
- * should be marked for translation. Example: I18N_NOOP("KEdit")
+ * @param programName A program name string to be used for display
+ * purposes. This string should be marked for
+ * translation. Example: I18N_NOOP("KEdit")
* @param _description A short description of what your application is about.
* @param _version A version.
- * @param noKApp Don't add commandline options for QApplication/ KApplication
+ * @param noKApp Set this true to not add commandline options for
+ * QApplication / KApplication
*/
static void init(int _argc, char **_argv, const char *_appname,
const char* programName, const char *_description,
const char *_version, bool noKApp = false);
/**
* @deprecated
+ * You should convert any calls to this method to use the one
+ * above, by adding in the program name to be used for display
+ * purposes. Do not forget to mark it for translation using I18_NOOP.
*/
static void init(int _argc, char **_argv,
const char *_appname, const char *_description,
const char *_version, bool noKApp = false) KDE_DEPRECATED;
@@ -249,26 +260,32 @@ public:
/**
* Initialize class.
*
* This function should be called as the very first thing in
- * your application.
+ * your application. It uses KAboutData to replace some of the
+ * arguments that would otherwise be required.
+ *
* @param _argc As passed to @p main(...).
* @param _argv As passed to @p main(...).
* @param about A KAboutData object describing your program.
- * @param noKApp Don't add commandline options for QApplication / KApplication
+ * @param noKApp Set this true to not add commandline options for
+ * QApplication / KApplication
*/
static void init(int _argc, char **_argv,
const KAboutData *about, bool noKApp = false);
/**
* Initialize Class
*
- * This function should be called as the very first thing in
- * your application.
+ * This function should be called as the very first thing in your
+ * application. This method will rarely be used, since it doesn't
+ * provide any argument parsing. It does provide access to the
+ * KAboutData information.
* This method is exactly the same as calling
- * init(0,0, const KAboutData *about, true)
- * This method will rarely be used
+ * init(0,0, const KAboutData *about, true).
+ *
* @param about the about data.
+ * \see KAboutData
*/
static void init(const KAboutData *about);
/**
@@ -281,17 +298,18 @@ public:
*
* \code
* static KCmdLineOptions options[] =
* {
- * { "option1 \<argument>", I18N_NOOP("Description 1"), "default" },
+ * { "option1 \<argument>", I18N_NOOP("Description 1"), "my_extra_arg" },
* { "o", 0, 0 },
* { "option2", I18N_NOOP("Description 2"), 0 },
* { "nooption3", I18N_NOOP("Description 3"), 0 },
* KCmdLineLastOption
* }
* \endcode
*
- * @li "option1" is an option that requires an additional argument
+ * @li "option1" is an option that requires an additional argument,
+ * but if one is not provided, it uses "my_extra_arg".
* @li "option2" is an option that can be turned on. The default is off.
* @li "option3" is an option that can be turned off. The default is on.
* @li "o" does not have a description. It is an alias for the option
* that follows. In this case "option2".
@@ -305,29 +323,32 @@ public:
* if (args->count() == 0) KCmdLineArgs::usage(i18n("No file specified!"));
* \endcode
*
* In BNF:
+ * \code
* cmd = myapp [options] file
* options = (option)*
* option = --option1 \<argument> |
* (-o | --option2 | --nooption2) |
* ( --option3 | --nooption3 )
+ * \endcode
*
* Instead of "--option3" one may also use "-option3"
*
* Usage examples:
*
* @li "myapp --option1 test"
- * @li "myapp" (same as "myapp --option1 default")
+ * @li "myapp" (same as "myapp --option1 my_extra_arg")
* @li "myapp --option2"
- * @li "myapp --nooption2" (same as "myapp")
+ * @li "myapp --nooption2" (same as "myapp", since it is off by default)
* @li "myapp -o" (same as "myapp --option2")
* @li "myapp --nooption3"
- * @li "myapp --option3 (same as "myapp")
- * @li "myapp --option2 --nooption2" (same as "myapp")
+ * @li "myapp --option3 (same as "myapp", since it is on by default)
+ * @li "myapp --option2 --nooption2" (same as "myapp", because it
+ * option2 is off by default, and the last usage applies)
* @li "myapp /tmp/file"
*
- * @param options A list of options thath your code supplies.
+ * @param options A list of options that your code supplies.
* @param name the name of the option, can be 0.
* @param id A name with which these options can be identified, can be 0.
* @param afterId The options are inserted after this set of options, can be 0.
*/
@@ -396,8 +417,10 @@ public:
* of the form:
* \code
* { "option \<argument>", I18N_NOOP("Description"), "default" }
* \endcode
+ * You cannot test for the presence of an alias - you must always
+ * test for the full option.
*
* @param option The name of the option without '-'.
*
* @return The value of the option. If the option was not
@@ -414,10 +437,12 @@ public:
* of the form:
* \code
* { "option \<argument>", I18N_NOOP("Description"), "default" }
* \endcode
+ * You cannot test for the presence of an alias - you must always
+ * test for the full option.
*
- * @param option The name of the option without '-'.
+ * @param option The name of the option, without '-' or '-no'.
*
* @return A list of all option values. If no option was present
* on the command line, an empty list is returned.
*/
@@ -427,18 +452,16 @@ public:
* Read out a boolean option or check for the presence of string option.
*
* @param option The name of the option without '-' or '-no'.
*
- * @return The value of the option. If the option was not
- * present on the command line the default is returned.
- * If the option is listed as 'no\<option>' the
- * default is true.
- * If the option is listed as '\<option>' the
- * default is false.
- *
- * If the option is listed as '\<option> \<arg>'
- * this function returns @p true if the option was present
- * and @p false otherwise.
+ * @return The value of the option. It will be true if the option
+ * was specifically turned on in the command line, or if the option
+ * is turned on by default (in the KCmdLineOptions list) and was
+ * not specifically turned off in the command line. Equivalently,
+ * it will be false if the option was specifically turned off in
+ * the command line, or if the option is turned off by default (in
+ * the KCmdLineOptions list) and was not specifically turned on in
+ * the command line.
*/
bool isSet(const char *option) const;
/**
Index: kconfigskeleton.h
===================================================================
RCS file: /home/kde/kdelibs/kdecore/kconfigskeleton.h,v
retrieving revision 1.15
diff -u -4 -p -r1.15 kconfigskeleton.h
--- kconfigskeleton.h 22 Oct 2003 11:53:50 -0000 1.15
+++ kconfigskeleton.h 2 Nov 2003 20:04:31 -0000
@@ -57,9 +57,9 @@
/**
* Constructor.
*
* @param group Config file group.
- * @param name Config file key.
+ * @param key Config file key.
*/
KConfigSkeletonItem(const QString & group, const QString & key)
:mGroup(group),mKey(key), mIsImmutable(true)
{
Index: kstandarddirs.h
===================================================================
RCS file: /home/kde/kdelibs/kdecore/kstandarddirs.h,v
retrieving revision 1.110
diff -u -4 -p -r1.110 kstandarddirs.h
--- kstandarddirs.h 20 Oct 2003 16:09:04 -0000 1.110
+++ kstandarddirs.h 2 Nov 2003 20:04:32 -0000
@@ -355,9 +355,9 @@ public:
/**
* Returns a QStringList list of pathnames in the system path.
*
- * @param pathstr The path which will be searched. If this is
+ * @param pstr The path which will be searched. If this is
* null (default), the $PATH environment variable will
* be searched.
*
* @return a QStringList list of pathnames in the system path.
Index: ksycocafactory.cpp
===================================================================
RCS file: /home/kde/kdelibs/kdecore/ksycocafactory.cpp,v
retrieving revision 1.24
diff -u -4 -p -r1.24 ksycocafactory.cpp
--- ksycocafactory.cpp 7 Aug 2002 21:26:33 -0000 1.24
+++ ksycocafactory.cpp 2 Nov 2003 20:04:32 -0000
@@ -183,7 +183,7 @@ KSycocaEntry::List KSycocaFactory::allEn
delete [] offsetList;
return list;
}
-void KSycocaFactory::virtual_hook( int, void* )
+void KSycocaFactory::virtual_hook( int id, void* data)
{ /*BASE::virtual_hook( id, data );*/ }
>> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscribe <<
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic