QCommandLineParser: improve documentation

Based on feedback from Thiago

Change-Id: I8912447197e636732e5b8ac37e77d18b54e9b43d
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

4 files changed, 171 insertions, 70 deletions

diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp
index d4c745215f..67d5f41b38 100644
--- a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp
@@ -38,7 +38,14 @@
 **
 ****************************************************************************/
 
+#include <QCommandLineOption>
+
+int main()
+{
+
 //! [0]
 QCommandLineOption verboseOption("verbose", "Verbose mode. Prints out more information.");
 QCommandLineOption outputOption(QStringList() << "o" << "output", "Write generated data into <file>.", "file");
 //! [0]
+
+}
diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser.cpp
index 569cb6af80..0ec45e04a7 100644
--- a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser.cpp
@@ -38,11 +38,32 @@
 **
 ****************************************************************************/
 
+#include <qcommandlineparser.h>
+
+int main(int argc, char **argv)
+{
+
+{
+QCommandLineParser parser;
 //! [0]
 bool verbose = parser.isSet("verbose");
 //! [0]
+}
 
+{
 //! [1]
+QCoreApplication app(argc, argv);
+QCommandLineParser parser;
+QCommandLineOption verboseOption("verbose");
+parser.addOption(verboseOption);
+parser.process(app);
+bool verbose = parser.isSet(verboseOption);
+//! [1]
+}
+
+{
+QCommandLineParser parser;
+//! [2]
 // Usage: image-editor file
 //
 // Arguments:
@@ -62,9 +83,14 @@ parser.addPositionalArgument("urls", QCoreApplication::translate("main", "URLs t
 //   destination           Destination directory.
 parser.addPositionalArgument("source", QCoreApplication::translate("main", "Source file to copy."));
 parser.addPositionalArgument("destination", QCoreApplication::translate("main", "Destination directory."));
-//! [1]
-
 //! [2]
+}
+
+{
+//! [3]
+QCoreApplication app(argc, argv);
+QCommandLineParser parser;
+
 parser.addPositionalArgument("command", "The command to execute.");
 
 // Call parse() to find out the positional arguments.
@@ -80,6 +106,7 @@ if (command == "resize") {
     // ...
 }
 
+/*
 This code results in context-dependent help:
 
 $ tool --help
@@ -96,46 +123,16 @@ Options:
 
 Arguments:
   resize         Resize the object to a new size.
-
-//! [2]
-
+*/
 //! [3]
-int main(int argc, char *argv[])
-{
-    QCoreApplication app(argc, argv);
-    app.setApplicationName("my-copy-program");
-    app.setApplicationVersion("1.0");
-
-    QCommandLineParser parser;
-    parser.addHelpOption("Test helper");
-    parser.addVersionOption();
-    parser.addRemainingArgument("source", QCoreApplication::translate("main", "Source file to copy."));
-    parser.addRemainingArgument("destination", QCoreApplication::translate("main", "Destination directory."));
-
-    // A boolean option with a single name (-p)
-    QCommandLineOption showProgressOption("p", QCoreApplication::translate("main", "Show progress during copy"));
-    parser.addOption(showProgressOption);
-
-    // A boolean option with multiple names (-f, --force)
-    QCommandLineOption forceOption(QStringList() << "f" << "force", "Overwrite existing files.");
-    parser.addOption(forceOption);
-
-    // An option with a value
-    QCommandLineOption targetDirectoryOption(QStringList() << "t" << "target-directory",
-            QCoreApplication::translate("main", "Copy all source files into <directory>."),
-            QCoreApplication::translate("main", "directory"));
-    parser.addOption(targetDirectoryOption);
-
-    // Process the actual command line arguments given by the user
-    parser.process(app);
-
-    const QStringList args = parser.remainingArguments();
-    // source is args.at(0), destination is args.at(1)
+}
 
-    bool showProgress = parser.isSet(showProgressOption);
-    bool force = parser.isSet(forceOption);
-    QString targetDir = parser.value(targetDirectoryOption);
-    // ...
+{
+//! [4]
+QCommandLineParser parser;
+parser.setApplicationDescription(QCoreApplication::translate("main", "The best application in the world"));
+parser.addHelpOption();
+//! [4]
 }
 
-//! [3]
+}
diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser_main.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser_main.cpp
new file mode 100644
index 0000000000..46b4274301
--- /dev/null
+++ b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser_main.cpp
@@ -0,0 +1,83 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 David Faure <faure@kde.org>
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <qcommandlineparser.h>
+
+//! [0]
+int main(int argc, char *argv[])
+{
+    QCoreApplication app(argc, argv);
+    QCoreApplication::setApplicationName("my-copy-program");
+    QCoreApplication::setApplicationVersion("1.0");
+
+    QCommandLineParser parser;
+    parser.setApplicationDescription("Test helper");
+    parser.addHelpOption();
+    parser.addVersionOption();
+    parser.addPositionalArgument("source", QCoreApplication::translate("main", "Source file to copy."));
+    parser.addPositionalArgument("destination", QCoreApplication::translate("main", "Destination directory."));
+
+    // A boolean option with a single name (-p)
+    QCommandLineOption showProgressOption("p", QCoreApplication::translate("main", "Show progress during copy"));
+    parser.addOption(showProgressOption);
+
+    // A boolean option with multiple names (-f, --force)
+    QCommandLineOption forceOption(QStringList() << "f" << "force", "Overwrite existing files.");
+    parser.addOption(forceOption);
+
+    // An option with a value
+    QCommandLineOption targetDirectoryOption(QStringList() << "t" << "target-directory",
+            QCoreApplication::translate("main", "Copy all source files into <directory>."),
+            QCoreApplication::translate("main", "directory"));
+    parser.addOption(targetDirectoryOption);
+
+    // Process the actual command line arguments given by the user
+    parser.process(app);
+
+    const QStringList args = parser.positionalArguments();
+    // source is args.at(0), destination is args.at(1)
+
+    bool showProgress = parser.isSet(showProgressOption);
+    bool force = parser.isSet(forceOption);
+    QString targetDir = parser.value(targetDirectoryOption);
+    // ...
+}
+
+//! [0]
diff --git a/src/corelib/tools/qcommandlineparser.cpp b/src/corelib/tools/qcommandlineparser.cpp
index ae6079ab0b..282004384a 100644
--- a/src/corelib/tools/qcommandlineparser.cpp
+++ b/src/corelib/tools/qcommandlineparser.cpp
@@ -160,7 +160,7 @@ QStringList QCommandLineParserPrivate::aliases(const QString &optionName) const
     passing \c{-v} on the command line. In the default parsing mode, short options
     can be written in a compact form, for instance \c{-abc} is equivalent to \c{-a -b -c}.
     The parsing mode for can be set to ParseAsLongOptions, in which case \c{-abc}
-    will be parsed as the long option \a{abc}.
+    will be parsed as the long option \c{abc}.
 
     Long options are more than one letter long and cannot be compacted together.
     The long option \c{verbose} would be passed as \c{--verbose} or \c{-verbose}.
@@ -180,7 +180,7 @@ QStringList QCommandLineParserPrivate::aliases(const QString &optionName) const
     as one of its names, and handling the option explicitly.
 
     Example:
-    \snippet code/src_corelib_tools_qcommandlineparser.cpp 3
+    \snippet code/src_corelib_tools_qcommandlineparser_main.cpp 0
 
     Known limitation: the parsing of Qt options inside QCoreApplication and subclasses
     happens before QCommandLineParser exists, so it can't take it into account. This
@@ -297,10 +297,7 @@ QCommandLineOption QCommandLineParser::addVersionOption()
     which will be displayed when this option is used.
 
     Example:
-    \code
-        setApplicationDescription(QCoreApplication::translate("main", "The best application in the world"));
-        addHelpOption();
-    \endcode
+    \snippet code/src_corelib_tools_qcommandlineparser_main.cpp 0
 
     Returns the option instance, which can be used to call isSet().
 */
@@ -319,8 +316,6 @@ QCommandLineOption QCommandLineParser::addHelpOption()
 
 /*!
     Sets the application \a description shown by helpText().
-    Most applications don't need to call this directly, addHelpOption()
-    also sets the application description.
 */
 void QCommandLineParser::setApplicationDescription(const QString &description)
 {
@@ -328,8 +323,7 @@ void QCommandLineParser::setApplicationDescription(const QString &description)
 }
 
 /*!
-    Returns the application description set in setApplicationDescription()
-    or addHelpOption().
+    Returns the application description set in setApplicationDescription().
 */
 QString QCommandLineParser::applicationDescription() const
 {
@@ -344,7 +338,7 @@ QString QCommandLineParser::applicationDescription() const
     the \a name will be appended.
 
     Example:
-    \snippet code/src_corelib_tools_qcommandlineparser.cpp 1
+    \snippet code/src_corelib_tools_qcommandlineparser.cpp 2
 
     \sa addHelpOption(), helpText()
 */
@@ -366,7 +360,7 @@ void QCommandLineParser::addPositionalArgument(const QString &name, const QStrin
     accordingly.
 
     Example:
-    \snippet code/src_corelib_tools_qcommandlineparser.cpp 2
+    \snippet code/src_corelib_tools_qcommandlineparser.cpp 3
 */
 void QCommandLineParser::clearPositionalArguments()
 {
@@ -376,7 +370,7 @@ void QCommandLineParser::clearPositionalArguments()
 /*!
     Parses the command line \a arguments.
 
-    Most programs don't need to call this, a simple call to process(app) is enough.
+    Most programs don't need to call this, a simple call to process() is enough.
 
     parse() is more low-level, and only does the parsing. The application will have to
     take care of the error handling, using errorText() if parse() returns false.
@@ -388,7 +382,7 @@ void QCommandLineParser::clearPositionalArguments()
 
     Don't forget that \a arguments must start with the name of the executable (ignored, though).
 
-    Return false in case of a parse error (unknown option or missing value); returns true otherwise.
+    Returns false in case of a parse error (unknown option or missing value); returns true otherwise.
 
     \sa process()
 */
@@ -415,10 +409,13 @@ QString QCommandLineParser::errorText() const
 /*!
     Processes the command line \a arguments.
 
-    This means both parsing them, and handling the builtin options,
-    \c{--version} if addVersionOption was called, \c{--help} if addHelpOption was called,
-    as well as giving an error on unknown option names.
-    In each of these three cases, the current process will then stop, using the exit() function.
+    In addition to parsing the options (like parse()), this function also handles the builtin
+    options and handles errors.
+
+    The builtin options are \c{--version} if addVersionOption was called and \c{--help} if addHelpOption was called.
+
+    When invoking one of these options, or when an error happens (for instance an unknown option was
+    passed), the current process will then stop, using the exit() function.
 
     \sa QCoreApplication::arguments(), parse()
  */
@@ -517,17 +514,13 @@ bool QCommandLineParserPrivate::parseOptionValue(const QString &optionName, cons
 /*!
     \internal
 
-    Parse the list of arguments \a arguments.
+    Parse the list of arguments \a args, and fills in
+    optionNames, optionValuesHash, unknownOptionNames, positionalArguments, and errorText.
 
     Any results from a previous parse operation are removed.
+
     The parser will not look for further options once it encounters the option
     \c{--}; this does not include when \c{--} follows an option that requires a value.
-
-    Options that were successfully recognized, and their values, are
-    removed from the input list. If \c m_bRemoveUnknownLongNames is
-    \c true, unrecognized options are removed and placed into a list of
-    unknown option names. Anything left over is placed into a list of
-    leftover arguments.
  */
 bool QCommandLineParserPrivate::parse(const QStringList &args)
 {
@@ -632,8 +625,6 @@ bool QCommandLineParserPrivate::parse(const QStringList &args)
 
     Returns true if the option \a name was set, false otherwise.
 
-    This is the recommended way to check for options with no values.
-
     The name provided can be any long or short name of any option that was
     added with \c addOption(). All the options names are treated as being
     equivalent. If the name is not recognized or that option was not present,
@@ -671,7 +662,7 @@ bool QCommandLineParser::isSet(const QString &name) const
 
     An empty string is returned if the option does not take a value.
 
-    \sa values()
+    \sa values(), QCommandLineOption::setDefaultValue(), QCommandLineOption::setDefaultValues()
  */
 
 QString QCommandLineParser::value(const QString &optionName) const
@@ -700,7 +691,7 @@ QString QCommandLineParser::value(const QString &optionName) const
 
     An empty list is returned if the option does not take a value.
 
-    \sa value()
+    \sa value(), QCommandLineOption::setDefaultValue(), QCommandLineOption::setDefaultValues()
  */
 
 QStringList QCommandLineParser::values(const QString &optionName) const
@@ -720,7 +711,14 @@ QStringList QCommandLineParser::values(const QString &optionName) const
 
 /*!
     \overload
+    Checks whether the \a option was passed to the application.
+
     Returns true if the \a option was set, false otherwise.
+
+    This is the recommended way to check for options with no values.
+
+    Example:
+    \snippet code/src_corelib_tools_qcommandlineparser.cpp 1
 */
 bool QCommandLineParser::isSet(const QCommandLineOption &option) const
 {
@@ -731,6 +729,14 @@ bool QCommandLineParser::isSet(const QCommandLineOption &option) const
     \overload
     Returns the option value found for the given \a option, or
     an empty string if not found.
+
+    For options found by the parser, the last value found for
+    that option is returned. If the option wasn't specified on the command line,
+    the default value is returned.
+
+    An empty string is returned if the option does not take a value.
+
+    \sa values(), QCommandLineOption::setDefaultValue(), QCommandLineOption::setDefaultValues()
 */
 QString QCommandLineParser::value(const QCommandLineOption &option) const
 {
@@ -741,6 +747,14 @@ QString QCommandLineParser::value(const QCommandLineOption &option) const
     \overload
     Returns a list of option values found for the given \a option,
     or an empty list if not found.
+
+    For options found by the parser, the list will contain an entry for
+    each time the option was encountered by the parser. If the option wasn't
+    specified on the command line, the default values are returned.
+
+    An empty list is returned if the option does not take a value.
+
+    \sa value(), QCommandLineOption::setDefaultValue(), QCommandLineOption::setDefaultValues()
 */
 QStringList QCommandLineParser::values(const QCommandLineOption &option) const
 {