QCommandLineParser: improve documentation

Based on feedback from Thiago

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

3 files changed, 128 insertions, 41 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]