API-Documentation: Add the Utils-library.

Fix API after doc template change.

doc/api/api.pro

@@ -37,8 +37,6 @@ equals(QMAKE_DIR_SEP, /) {   # unix, mingw+msys
 HELP_FILES     = $$PWD/qtcreator-api.qdocconf
 HELP_DEP_FILES = $$PWD/qtcreator-api.qdoc \
                  $$PWD/coding-style.qdoc \
-                 $$PWD/../qt-defines.qdocconf \
-                 $$PWD/../qt-html-templates.qdocconf \
                  $$PWD/qtcreator-api.qdocconf
 
 docs.name = CREATE API DOC

doc/api/qtcreator-api.qdoc

@@ -60,6 +60,10 @@
     \o Implements the plugin loader framework. Provides a base class for plugins and
     basic mechanisms for plugin interaction like an object pool.
 
+    \row
+    \o \l{Utils}
+    \o General utility library.
+
     \endtable
 
     \section2 Additional libraries

doc/api/qtcreator-api.qdocconf

@@ -9,6 +9,7 @@ headerdirs              = . \
                           ../../src/libs/aggregation \
                           ../../src/libs/cplusplus \
                           ../../src/libs/extensionsystem \
+                          ../../src/libs/utils \
                           ../../src/libs/qtcreatorcdbext \
                           ../../src/plugins/coreplugin \
                           ../../src/plugins/find \
@@ -19,6 +20,7 @@ sourcedirs              = . \
                           ../../src/libs/aggregation \
                           ../../src/libs/cplusplus \
                           ../../src/libs/extensionsystem \
+                          ../../src/libs/utils \
                           ../../src/libs/qtcreatorcdbext \
                           ../../src/plugins/coreplugin \
                           ../../src/plugins/find \

src/libs/utils/basevalidatinglineedit.cpp

@@ -37,6 +37,27 @@
 
 enum { debug = 0 };
 
+/*!
+    \namespace Utils
+    General utility library namespace
+*/
+
+/*! \class Utils::BaseValidatingLineEdit
+
+    \brief Base class for line edits that perform validation.
+
+    Performs validation in a virtual  validate() function to be implemented in
+    derived classes.
+    When invalid, the text color will turn red and a tooltip will
+    contain the error message. This approach is less intrusive than a
+    QValidator which will prevent the user from entering certain characters.
+
+    The widget has a concept of an "initialText" which can be something like
+    "<Enter name here>". This results in state 'DisplayingInitialText', which
+    is not valid, but is not marked red.
+*/
+
+
 namespace Utils {
 
 struct BaseValidatingLineEditPrivate {

src/libs/utils/basevalidatinglineedit.h

@@ -42,17 +42,6 @@ namespace Utils {
 
 struct BaseValidatingLineEditPrivate;
 
-/**
- * Base class for validating line edits that performs validation in a virtual
- * validate() function to be implemented in derived classes.
- * When invalid, the text color will turn red and a tooltip will
- * contain the error message. This approach is less intrusive than a
- * QValidator which will prevent the user from entering certain characters.
- *
- * The widget has a concept of an "initialText" which can be something like
- * "<Enter name here>". This results in state 'DisplayingInitialText', which
- * is not valid, but is not marked red.
- */
 class QTCREATOR_UTILS_EXPORT BaseValidatingLineEdit : public QLineEdit
 {
     Q_OBJECT

src/libs/utils/checkablemessagebox.cpp

@@ -37,6 +37,16 @@
 #include <QtGui/QPushButton>
 #include <QtCore/QDebug>
 
+/*!
+    \class Utils::CheckableMessageBox
+
+     \brief A messagebox suitable for questions with a
+     "Do not ask me again" checkbox.
+
+    Emulates the QMessageBox API with
+    static conveniences. The message label can open external URLs.
+*/
+
 namespace Utils {
 
 struct CheckableMessageBoxPrivate {

src/libs/utils/checkablemessagebox.h

@@ -44,10 +44,6 @@ namespace Utils {
 
 struct CheckableMessageBoxPrivate;
 
-/* A messagebox suitable for questions with a
- * "Do not ask me again" checkbox. Emulates the QMessageBox API with
- * static conveniences. The message label can open external URLs. */
-
 class QTCREATOR_UTILS_EXPORT CheckableMessageBox : public QDialog
 {
     Q_OBJECT

src/libs/utils/classnamevalidatinglineedit.cpp

@@ -38,6 +38,13 @@
 #include <QtCore/QDebug>
 #include <QtCore/QRegExp>
 
+/*!
+    \class Utils::ClassNameValidatingLineEdit
+
+    \brief A Line edit that validates a C++ class name and emits a signal
+    to derive suggested file names from it.
+*/
+
 namespace Utils {
 
 struct ClassNameValidatingLineEditPrivate {

src/libs/utils/classnamevalidatinglineedit.h

@@ -41,9 +41,6 @@ namespace Utils {
 
 struct ClassNameValidatingLineEditPrivate;
 
-/* A Line edit that validates a C++ class name and emits a signal
- * to derive suggested file names from it. */
-
 class QTCREATOR_UTILS_EXPORT ClassNameValidatingLineEdit
   : public Utils::BaseValidatingLineEdit
 {

src/libs/utils/detailswidget.cpp

@@ -44,19 +44,27 @@
 #include <QtGui/QScrollArea>
 #include <QtGui/QApplication>
 
+/*!
+    \class Utils::DetailsWidget
+
+    \brief Widget a button to expand a 'Details' area.
+
+    This widget is using a grid layout and places the items
+    in the following way:
+
+    \code
++------------+-------------------------+---------------+
++summaryLabel|              toolwidget | detailsButton |
++------------+-------------------------+---------------+
+|                  widget                              |
++------------+-------------------------+---------------+
+    \endcode
+*/
+
 namespace Utils {
 
     static const int MARGIN=8;
 
-    // This widget is using a grid layout and places the items
-    // in the following way:
-    //
-    // +------------+-------------------------+---------------+
-    // +summaryLabel|              toolwidget | detailsButton |
-    // +------------+-------------------------+---------------+
-    // |                  widget                              |
-    // +------------+-------------------------+---------------+
-
     struct DetailsWidgetPrivate {
         DetailsWidgetPrivate(QWidget *parent);
 

src/libs/utils/faketooltip.cpp

@@ -36,6 +36,14 @@
 #include <QtGui/QStyleOption>
 #include <QtGui/QStylePainter>
 
+/*!
+    \class Utils::FakeToolTip
+
+    \brief A widget that pretends to be a tooltip.
+
+    By default it has Qt::WA_DeleteOnClose set.
+*/
+
 namespace Utils {
 
 FakeToolTip::FakeToolTip(QWidget *parent) :

src/libs/utils/faketooltip.h

@@ -40,10 +40,6 @@
 
 namespace Utils {
 
-/**
- * A widget that pretends to be a tooltip. By default it has
- * Qt::WA_DeleteOnClose set.
- */
 class QTCREATOR_UTILS_EXPORT FakeToolTip : public QWidget
 {
     Q_OBJECT

src/libs/utils/fancylineedit.cpp

@@ -46,6 +46,19 @@
 #include <QtGui/QStyle>
 #include <QtGui/QPaintEvent>
 
+/*!
+    \class Utils::FancyLineEdit
+
+    \brief A line edit with an embedded pixmap on one side that is connected to
+    a menu.
+
+    Additionally, it can display a grayed hintText (like "Type Here to")
+    when not focused and empty. When connecting to the changed signals and
+    querying text, one has to be aware that the text is set to that hint
+    text if isShowingHintText() returns true (that is, does not contain
+    valid user input).
+ */
+
 enum { margin = 6 };
 
 #define ICONBUTTON_HEIGHT 18

src/libs/utils/fancylineedit.h

@@ -66,14 +66,6 @@ private:
     QPixmap m_pixmap;
 };
 
-
-/* A line edit with an embedded pixmap on one side that is connected to
- * a menu. Additionally, it can display a grayed hintText (like "Type Here to")
- * when not focused and empty. When connecting to the changed signals and
- * querying text, one has to be aware that the text is set to that hint
- * text if isShowingHintText() returns true (that is, does not contain
- * valid user input).
- */
 class QTCREATOR_UTILS_EXPORT FancyLineEdit : public QLineEdit
 {
     Q_DISABLE_COPY(FancyLineEdit)

src/libs/utils/fancymainwindow.cpp

@@ -49,6 +49,15 @@ static const char dockWidgetActiveState[] = "DockWidgetActiveState";
 
 namespace Utils {
 
+/*! \class Utils::FancyMainWindow
+
+    \brief MainWindow with dock widgets and additional "lock" functionality
+    (locking the dock widgets in place) and "reset layout" functionality.
+
+    The dock actions and the additional actions should be accessible
+    in a Window-menu.
+*/
+
 struct FancyMainWindowPrivate
 {
     FancyMainWindowPrivate();

src/libs/utils/fancymainwindow.h

@@ -46,10 +46,6 @@ namespace Utils {
 
 struct FancyMainWindowPrivate;
 
-// MainWindow with dock widgets and additional "lock" functionality
-// (locking the dock widgets in place) and "reset layout" functionality.
-// The dock actions and the additional actions should be accessible
-// in a Window-menu.
 class QTCREATOR_UTILS_EXPORT FancyMainWindow : public QMainWindow
 {
     Q_OBJECT

src/libs/utils/fileinprojectfinder.cpp

@@ -38,21 +38,24 @@
 
 namespace Utils {
 
-/**
+/*!
-  \class FileInProjectFinder
+  \class Utils::FileInProjectFinder
 
-  Helper class to find the 'original' file in the project directory for a given file path.
+  \brief Helper class to find the 'original' file in the project directory for a given file path.
 
   Often files are copied in the build + deploy process. findFile() searches for an existing file
   in the project directory for a given file path:
 
   E.g. following file paths:
-      C:/app-build-desktop/qml/app/main.qml (shadow build directory)
+  \list
-      C:/Private/e3026d63/qml/app/main.qml  (Application data folder on Symbian device)
+  \i C:/app-build-desktop/qml/app/main.qml (shadow build directory)
-      /Users/x/app-build-desktop/App.app/Contents/Resources/qml/App/main.qml (folder on Mac OS X)
+  \i C:/Private/e3026d63/qml/app/main.qml  (Application data folder on Symbian device)
- should all be mapped to
+  \i /Users/x/app-build-desktop/App.app/Contents/Resources/qml/App/main.qml (folder on Mac OS X)
-      $PROJECTDIR/qml/app/main.qml
+  \endlist
-  */
+
+ should all be mapped to $PROJECTDIR/qml/app/main.qml
+*/
+
 FileInProjectFinder::FileInProjectFinder()
 {
 }

src/libs/utils/filenamevalidatinglineedit.cpp

@@ -37,6 +37,13 @@
 #include <QtCore/QRegExp>
 #include <QtCore/QDebug>
 
+/*!
+  \class Utils::FileNameValidatingLineEdit
+
+  \brief A control that let's the user choose a (base) file name, based on a QLineEdit. Has
+   some validation logic for embedding into QWizardPage.
+*/
+
 namespace Utils {
 
 #define WINDOWS_DEVICES "CON|AUX|PRN|COM1|COM2|LPT1|LPT2|NUL"

src/libs/utils/filenamevalidatinglineedit.h

@@ -38,10 +38,6 @@
 
 namespace Utils {
 
-/**
- * A control that let's the user choose a file name, based on a QLineEdit. Has
- * some validation logic for embedding into QWizardPage.
- */
 class QTCREATOR_UTILS_EXPORT FileNameValidatingLineEdit : public BaseValidatingLineEdit
 {
     Q_OBJECT

src/libs/utils/filewizarddialog.cpp

@@ -36,6 +36,13 @@
 
 #include <QtGui/QAbstractButton>
 
+/*!
+  \class Utils::FileWizardDialog
+
+  \brief Standard wizard for a single file letting the user choose name
+   and path. Custom pages can be added via Core::IWizardExtension.
+*/
+
 namespace Utils {
 
 FileWizardDialog::FileWizardDialog(QWidget *parent) :

src/libs/utils/filewizarddialog.h

@@ -41,11 +41,6 @@ namespace Utils {
 
 class FileWizardPage;
 
-/*
-   Standard wizard for a single file letting the user choose name
-   and path. Custom pages can be added via Core::IWizardExtension.
-*/
-
 class QTCREATOR_UTILS_EXPORT FileWizardDialog : public Wizard {
     Q_OBJECT
     Q_DISABLE_COPY(FileWizardDialog)

src/libs/utils/filewizardpage.cpp

@@ -34,6 +34,16 @@
 #include "filewizardpage.h"
 #include "ui_filewizardpage.h"
 
+/*!
+  \class Utils::FileWizardPage
+
+  \brief Standard wizard page for a single file letting the user choose name
+  and path.
+
+  The name and path labels can be changed. By default they are simply "Name:"
+  and "Path:".
+*/
+
 namespace Utils {
 
 struct FileWizardPagePrivate

src/libs/utils/filewizardpage.h

@@ -42,13 +42,6 @@ namespace Utils {
 
 struct FileWizardPagePrivate;
 
-/**
- * Standard wizard page for a single file letting the user choose name
- * and path. Sets the "FileNames" QWizard field.
- *
- * The name and path labels can be changed. By default they are simply "Name:"
- * and "Path:".
- */
 class QTCREATOR_UTILS_EXPORT FileWizardPage : public QWizardPage
 {
     Q_OBJECT

src/libs/utils/filterlineedit.cpp

@@ -33,15 +33,21 @@
 
 #include "filterlineedit.h"
 
+/*!
+    \class Utils::FilterLineEdit
+
+    \brief A fancy line edit customized for filtering purposes with a clear button.
+*/
+
 namespace Utils {
 
 FilterLineEdit::FilterLineEdit(QWidget *parent) :
    FancyLineEdit(parent),
    m_lastFilterText(text())
 {
-    // KDE has custom icons for this. Notice that icon namings are counter intuitive
+    // KDE has custom icons for this. Notice that icon namings are counter intuitive.
-    // If these icons are not avaiable we use the freedesktop standard name before
+    // If these icons are not available we use the freedesktop standard name before
-    // falling back to a bundled resource
+    // falling back to a bundled resource.
     QIcon icon = QIcon::fromTheme(layoutDirection() == Qt::LeftToRight ?
                      QLatin1String("edit-clear-locationbar-rtl") :
                      QLatin1String("edit-clear-locationbar-ltr"),

src/libs/utils/filterlineedit.h

@@ -38,8 +38,6 @@
 
 namespace Utils {
 
-/* A fancy line edit customized for filtering purposes with a clear button. */
-
 class QTCREATOR_UTILS_EXPORT FilterLineEdit : public FancyLineEdit
 {
     Q_OBJECT

src/libs/utils/ipaddresslineedit.cpp

@@ -35,6 +35,14 @@
 
 #include <QtGui/QRegExpValidator>
 
+/*!
+  \class Utils::IpAddressLineEdit
+
+  \brief A QLineEdit widget that validates the IP address inserted.
+
+  The valid address example is 192.168.1.12 or 192.168.1.12:8080.
+*/
+
 namespace Utils {
 
 // ------------------ IpAddressLineEditPrivate

src/libs/utils/ipaddresslineedit.h

@@ -42,11 +42,6 @@ namespace Utils {
 
 class IpAddressLineEditPrivate;
 
-/**
- * A LineEdit widget that validates the IP address inserted.
- * The valid address example is 192.168.1.12 or 192.168.1.12:8080
- */
-
 class QTCREATOR_UTILS_EXPORT IpAddressLineEdit : public QLineEdit
 {
     Q_OBJECT

src/libs/utils/linecolumnlabel.cpp

@@ -33,6 +33,13 @@
 
 #include "linecolumnlabel.h"
 
+/*!
+    \class Utils::LineColumnLabel
+
+    \brief A label suitable for displaying cursor positions, etc. with a fixed
+    width derived from a sample text.
+*/
+
 namespace Utils {
 
 LineColumnLabel::LineColumnLabel(QWidget *parent)

src/libs/utils/linecolumnlabel.h

@@ -39,9 +39,6 @@
 
 namespace Utils {
 
-/* A label suitable for displaying cursor positions, etc. with a fixed
- * with derived from a sample text. */
-
 class  QTCREATOR_UTILS_EXPORT LineColumnLabel : public QLabel
 {
     Q_DISABLE_COPY(LineColumnLabel)

src/libs/utils/navigationtreeview.cpp

@@ -40,6 +40,15 @@
 #include <QtGui/QKeyEvent>
 #endif
 
+/*!
+   \class Utils::NavigationTreeView
+
+   \brief General TreeView for any Side Bar widget.
+
+   Common initialization etc, e.g. Mac specific behaviour.
+   \sa Core::NavigationView, Core::INavigationWidgetFactory
+ */
+
 namespace Utils {
 
 NavigationTreeView::NavigationTreeView(QWidget *parent)

src/libs/utils/navigationtreeview.h

@@ -40,18 +40,11 @@
 
 namespace Utils {
 
-/*!
-   \class NavigationTreeView
-   \sa Core::NavigationView, Core::INavigationWidgetFactory
-
-   General TreeView for any Side Bar widget. Common initialization etc, e.g. Mac specific behaviour.
- */
-
 class QTCREATOR_UTILS_EXPORT NavigationTreeView : public QTreeView
 {
     Q_OBJECT
 public:
-    NavigationTreeView(QWidget *parent = 0);
+    explicit NavigationTreeView(QWidget *parent = 0);
 
 protected:
     void focusInEvent(QFocusEvent *event);

src/libs/utils/newclasswidget.cpp

@@ -45,6 +45,15 @@
 
 enum { debugNewClassWidget = 0 };
 
+/*! \class Utils::NewClassWidget
+
+    \brief Utility widget for 'New Class' wizards
+
+    Utility widget for 'New Class' wizards. Prompts the user
+    to enter a class name (optionally derived from some base class) and file
+    names for header, source and form files. Has some smart logic to derive
+    the file names from the class name. */
+
 namespace Utils {
 
 struct NewClassWidgetPrivate {

src/libs/utils/newclasswidget.h

@@ -46,12 +46,6 @@ namespace Utils {
 
 struct NewClassWidgetPrivate;
 
-/**
- * NewClassWidget: Utility widget for 'New Class' wizards. Prompts the user
- * to enter a class name (optionally derived from some base class) and file
- * names for header, source and form files. Has some smart logic to derive
- * the file names from the class name.
- */
 class QTCREATOR_UTILS_EXPORT NewClassWidget : public QWidget
 {
     Q_DISABLE_COPY(NewClassWidget)

src/libs/utils/parameteraction.cpp

@@ -33,6 +33,24 @@
 
 #include "parameteraction.h"
 
+/*!
+    \class Utils::ParameterAction
+
+    \brief Intended for actions that act on a 'current',
+     string-type parameter (typically a file name), for example 'Save file %1'.
+
+    The action has 2 states:
+    \list
+    \o <no current parameter> displaying "Do XX" (empty text)
+    \o <parameter present> displaying "Do XX with %1".
+    \endlist
+
+    Provides a slot to set the parameter, changing display
+    and enabled state accordingly.
+    The text passed in should already be translated; parameterText
+    should contain a %1 where the parameter is to be inserted.
+*/
+
 namespace Utils {
 
 ParameterAction::ParameterAction(const QString &emptyText,

src/libs/utils/parameteraction.h

@@ -40,15 +40,6 @@
 
 namespace Utils {
 
-/* ParameterAction: Intended for actions that act on a 'current',
- * string-type parameter (typically file name) and have 2 states:
- * 1) <no current parameter> displaying "Do XX" (empty text)
- * 2) <parameter present> displaying "Do XX with %1".
- * Provides a slot to set the parameter, changing display
- * and enabled state accordingly.
- * The text passed in should already be translated; parameterText
- * should contain a %1 where the parameter is to be inserted. */
-
 class QTCREATOR_UTILS_EXPORT ParameterAction : public QAction
 {
     Q_ENUMS(EnablingMode)

src/libs/utils/pathchooser.cpp

@@ -52,6 +52,15 @@
 #include <QtGui/QLineEdit>
 #include <QtGui/QPushButton>
 
+/*!
+    \class Utils::PathChooser
+
+    \brief A control that let's the user choose a path, consisting of a QLineEdit and
+    a "Browse" button.
+
+    Has some validation logic for embedding into QWizardPage.
+*/
+
 /*static*/ const char * const Utils::PathChooser::browseButtonLabel =
 #ifdef Q_WS_MAC
                    QT_TRANSLATE_NOOP("Utils::PathChooser", "Choose...");

src/libs/utils/pathchooser.h

@@ -49,10 +49,6 @@ namespace Utils {
 class Environment;
 class PathChooserPrivate;
 
-/**
- * A control that let's the user choose a path, consisting of a QLineEdit and
- * a "Browse" button. Has some validation logic for embedding into QWizardPage.
- */
 class QTCREATOR_UTILS_EXPORT PathChooser : public QWidget
 {
     Q_DISABLE_COPY(PathChooser)

src/libs/utils/pathlisteditor.cpp

@@ -50,6 +50,24 @@
 #include <QtCore/QDir>
 #include <QtCore/QDebug>
 
+/*!
+    \class Utils::PathListEditor
+
+    \brief A control that let's the user edit a list of (directory) paths
+    using the platform separator (';',':').
+
+    Typically used for
+    path lists controlled by environment variables, such as
+    PATH. It is based on a QPlainTextEdit as it should
+    allow for convenient editing and non-directory type elements like
+    \code
+    "etc/mydir1:$SPECIAL_SYNTAX:/etc/mydir2".
+    \endcode
+
+    When pasting text into it, the platform separator will be replaced
+    by new line characters for convenience.
+ */
+
 namespace Utils {
 
 // ------------ PathListPlainTextEdit:

src/libs/utils/pathlisteditor.h

@@ -47,17 +47,6 @@ namespace Utils {
 
 struct PathListEditorPrivate;
 
-/**
- * A control that let's the user edit a list of (directory) paths
- * using the platform separator (';',':'). Typically used for
- * path lists controlled by environment variables, such as
- * PATH. It is based on a QPlainTextEdit as it should
- * allow for convenient editing and non-directory type elements like
- * "etc/mydir1:$SPECIAL_SYNTAX:/etc/mydir2".
- * When pasting text into it, the platform separator will be replaced
- * by new line characters for convenience.
- */
-
 class QTCREATOR_UTILS_EXPORT PathListEditor : public QWidget
 {
     Q_DISABLE_COPY(PathListEditor)

src/libs/utils/projectintropage.cpp

@@ -39,6 +39,28 @@
 #include <QtCore/QDir>
 #include <QtCore/QFileInfo>
 
+
+/*!
+    \class Utils::ProjectIntroPage
+
+    \brief Standard wizard page for a project, letting the user choose name
+    and path.
+
+    Looks similar to FileWizardPage, but provides additional
+    functionality:
+    \list
+    \o Description label at the top for displaying introductory text
+    \o It does on the fly validation (connected to changed()) and displays
+       warnings/errors in a status label at the bottom (the page is complete
+       when fully validated, validatePage() is thus not implemented).
+    \endlist
+
+    Note: Careful when changing projectintropage.ui. It must have main
+    geometry cleared and QLayout::SetMinimumSize constraint on the main
+    layout, otherwise, QWizard will squeeze it due to its strange expanding
+    hacks.
+*/
+
 namespace Utils {
 
 struct ProjectIntroPagePrivate

src/libs/utils/projectintropage.h

@@ -42,19 +42,6 @@ namespace Utils {
 
 struct ProjectIntroPagePrivate;
 
-/* Standard wizard page for a single file letting the user choose name
- * and path. Looks similar to FileWizardPage, but provides additional
- * functionality:
- * - Description label at the top for displaying introductory text
- * - It does on the fly validation (connected to changed()) and displays
- *   warnings/errors in a status label at the bottom (the page is complete
- *   when fully validated, validatePage() is thus not implemented).
- *
- * Note: Careful when changing projectintropage.ui. It must have main
- * geometry cleared and QLayout::SetMinimumSize constraint on the main
- * layout, otherwise, QWizard will squeeze it due to its strange expanding
- * hacks. */
-
 class QTCREATOR_UTILS_EXPORT ProjectIntroPage : public QWizardPage
 {
     Q_OBJECT

src/libs/utils/qtcprocess.cpp

@@ -42,68 +42,11 @@
 
 using namespace Utils;
 
-/**
+/*!
- * \fn QStringList QtcProcess::splitArgs(
+    \class Utils::QtcProcess
- *         const QString &args, bool abortOnMeta, SplitError *err, const Environment *env)
+
- *
+    \brief This class provides functionality for dealing with shell-quoted process arguments.
- * Splits \a args according to system shell word splitting and quoting rules.
+*/
- *
- * \section Unix
- *
- * The behavior is based on the POSIX shell and bash:
- * \list
- * \li Whitespace splits tokens
- * \li The backslash quotes the following character
- * \li A string enclosed in single quotes is not split. No shell meta
- *     characters are interpreted.
- * \li A string enclosed in double quotes is not split. Within the string,
- *     the backslash quotes shell meta characters - if it is followed
- *     by a "meaningless" character, the backslash is output verbatim.
- * \list
- * If \a abortOnMeta is \c false, only the splitting and quoting rules apply,
- * while other meta characters (substitutions, redirections, etc.) are ignored.
- * If \a abortOnMeta is \c true, encounters of unhandled meta characters are
- * treated as errors.
- *
- * \section Windows
- *
- * The behavior is defined by the Microsoft C runtime:
- * \list
- * \li Whitespace splits tokens
- * \li A string enclosed in double quotes is not split
- *   \list
- *   \li 3N double quotes within a quoted string yield N literal quotes.
- *     This is not documented on MSDN.
- *   \endlist
- * \li Backslashes have special semantics iff they are followed by a double
- *     quote:
- *   \list
- *   \li 2N backslashes + double quote => N backslashes and begin/end quoting
- *   \li 2N+1 backslashes + double quote => N backslashes + literal quote
- *   \endlist
- * \endlist
- * Qt and many other implementations comply with this standard, but many do not.
- *
- * If \a abortOnMeta is \c true, cmd shell semantics are applied before
- * proceeding with word splitting:
- * \list
- * \li Cmd ignores \em all special chars between double quotes.
- *     Note that the quotes are \em not removed at this stage - the
- *     tokenization rules described above still apply.
- * \li The \c circumflex is the escape char for everything including itself.
- * \endlist
- * As the quoting levels are independent from each other and have different
- * semantics, you need a command line like \c{"foo "\^"" bar"} to get
- * \c{foo " bar}.
- *
- * \param cmd the command to split
- * \param abortOnMeta see above
- * \param err if not NULL, a status code will be stored at the pointer
- *  target, see \ref SplitError
- * \param env if not NULL, perform variable substitution with the
- *  given environment.
- * \return a list of unquoted words or an empty list if an error occurred
- */
 
 #ifdef Q_OS_WIN
 
@@ -255,6 +198,65 @@ static QStringList doSplitArgs(const QString &args, QtcProcess::SplitError *err)
     //not reached
 }
 
+/*!
+    Splits \a args according to system shell word splitting and quoting rules.
+
+    \section1 Unix
+
+    The behavior is based on the POSIX shell and bash:
+    \list
+    \i Whitespace splits tokens
+    \i The backslash quotes the following character
+    \i A string enclosed in single quotes is not split. No shell meta
+        characters are interpreted.
+    \i A string enclosed in double quotes is not split. Within the string,
+        the backslash quotes shell meta characters - if it is followed
+        by a "meaningless" character, the backslash is output verbatim.
+    \endlist
+    If \a abortOnMeta is \c false, only the splitting and quoting rules apply,
+    while other meta characters (substitutions, redirections, etc.) are ignored.
+    If \a abortOnMeta is \c true, encounters of unhandled meta characters are
+    treated as errors.
+
+    \section1 Windows
+
+    The behavior is defined by the Microsoft C runtime:
+    \list
+    \i Whitespace splits tokens
+    \i A string enclosed in double quotes is not split
+    \list
+        \i 3N double quotes within a quoted string yield N literal quotes.
+           This is not documented on MSDN.
+    \endlist
+    \i Backslashes have special semantics iff they are followed by a double quote:
+    \list
+        \i 2N backslashes + double quote => N backslashes and begin/end quoting
+        \i 2N+1 backslashes + double quote => N backslashes + literal quote
+    \endlist
+    \endlist
+    Qt and many other implementations comply with this standard, but many do not.
+
+    If \a abortOnMeta is \c true, cmd shell semantics are applied before
+    proceeding with word splitting:
+    \list
+    \i Cmd ignores \em all special chars between double quotes.
+        Note that the quotes are \em not removed at this stage - the
+        tokenization rules described above still apply.
+    \i The \c circumflex is the escape char for everything including itself.
+    \endlist
+    As the quoting levels are independent from each other and have different
+    semantics, you need a command line like \c{"foo "\^"" bar"} to get
+    \c{foo " bar}.
+
+    \param cmd the command to split
+    \param abortOnMeta see above
+    \param err if not NULL, a status code will be stored at the pointer
+    target, see \ref SplitError
+    \param env if not NULL, perform variable substitution with the
+    given environment.
+   \return a list of unquoted words or an empty list if an error occurred
+ */
+
 QStringList QtcProcess::splitArgs(const QString &_args, bool abortOnMeta, SplitError *err,
                                   const Environment *env, const QString *pwd)
 {

src/libs/utils/qtcprocess.h

@@ -43,9 +43,6 @@
 namespace Utils {
 class AbstractMacroExpander;
 
-/*!
-  This class provides functionality for dealing with shell-quoted process arguments.
-*/
 class QTCREATOR_UTILS_EXPORT QtcProcess : public QProcess
 {
     Q_OBJECT

src/libs/utils/savedaction.cpp

@@ -48,10 +48,8 @@
 #include <QtGui/QSpinBox>
 #include <QtGui/QGroupBox>
 
-
 using namespace Utils;
 
-
 //////////////////////////////////////////////////////////////////////////
 //
 // SavedAction
@@ -63,9 +61,6 @@ using namespace Utils;
 
     \brief The SavedAction class is a helper class for actions with persistent
     state.
-
-    \ingroup utils
-
 */
 
 SavedAction::SavedAction(QObject *parent)
@@ -426,7 +421,6 @@ void SavedAction::trigger(const QVariant &data)
     QAction::trigger();
 }
 
-
 //////////////////////////////////////////////////////////////////////////
 //
 // SavedActionSet

src/libs/utils/ssh/sftpchannel.cpp

@@ -41,8 +41,32 @@
 #include <QtCore/QDir>
 #include <QtCore/QFile>
 
-namespace Utils {
+/*!
+    \class Utils::SftpChannel
 
+    \brief This class provides SFTP operations.
+
+    Objects are created via SshConnection::createSftpChannel().
+    The channel needs to be initialized with
+    a call to initialize() and is closed via closeChannel(). After closing
+    a channel, no more operations are possible. It cannot be re-opened
+    using initialize(); use SshConnection::createSftpChannel() if you need
+    a new one.
+
+    After the initialized() signal has been emitted, operations can be started.
+    All SFTP operations are asynchronous (non-blocking) and can be in-flight
+    simultaneously (though callers must ensure that concurrently running jobs
+    are independent of each other, e.g. they must not write to the same file).
+    Operations are identified by their job id, which is returned by
+    the respective member function. If the function can right away detect that
+    the operation cannot succeed, it returns SftpInvalidJob. If an error occurs
+    later, the finished() signal is emitted for the respective job with a
+    non-empty error string.
+
+    Note that directory names must not have a trailing slash.
+*/
+
+namespace Utils {
 namespace Internal {
 namespace {
     const quint32 ProtocolVersion = 3;

src/libs/utils/ssh/sftpchannel.h

@@ -52,25 +52,6 @@ class SshChannelManager;
 class SshSendFacility;
 } // namespace Internal
 
-/*
- * This class provides SFTP operations.
- * Objects are created via SshConnection::createSftpChannel().
- * The channel needs to be initialized with
- * a call to initialize() and is closed via closeChannel(). After closing
- * a channel, no more operations are possible. It cannot be re-opened
- * using initialize(); use SshConnection::createSftpChannel() if you need
- * a new one.
- * After the initialized() signal has been emitted, operations can be started.
- * All SFTP operations are asynchronous (non-blocking) and can be in-flight
- * simultaneously (though callers must ensure that concurrently running jobs
- * are independent of each other, e.g. they must not write to the same file).
- * Operations are identified by their job id, which is returned by
- * the respective member function. If the function can right away detect that
- * the operation cannot succeed, it returns SftpInvalidJob. If an error occurs
- * later, the finished() signal is emitted for the respective job with a
- * non-empty error string.
- * Note that directory names must not have a trailing slash.
- */
 class QTCREATOR_UTILS_EXPORT SftpChannel : public QObject
 {
     Q_OBJECT

src/libs/utils/ssh/sshconnection.cpp

@@ -51,6 +51,15 @@
 #include <QtNetwork/QNetworkProxy>
 #include <QtNetwork/QTcpSocket>
 
+/*!
+    \class Utils::SshConnection
+
+    \brief This class provides an SSH connection, implementing protocol version 2.0
+
+    It can spawn channels for remote execution and SFTP operations (version 3).
+    It operates asynchronously (non-blocking) and is not thread-safe.
+*/
+
 namespace Utils {
 
 namespace {

src/libs/utils/ssh/sshconnection.h

@@ -70,11 +70,6 @@ struct QTCREATOR_UTILS_EXPORT SshConnectionParameters
 QTCREATOR_UTILS_EXPORT bool operator==(const SshConnectionParameters &p1, const SshConnectionParameters &p2);
 QTCREATOR_UTILS_EXPORT bool operator!=(const SshConnectionParameters &p1, const SshConnectionParameters &p2);
 
-/*
- * This class provides an SSH connection, implementing protocol version 2.0
- * It can spawn channels for remote execution and SFTP operations (version 3).
- * It operates asynchronously (non-blocking) and is not thread-safe.
- */
 class QTCREATOR_UTILS_EXPORT SshConnection : public QObject
 {
     Q_OBJECT

src/libs/utils/ssh/sshremoteprocess.cpp

@@ -41,6 +41,26 @@
 
 #include <QtCore/QTimer>
 
+/*!
+    \class SshRemoteProcess
+
+    \brief This class implements an SSH channel for running a remote process.
+
+    Objects are created via SshConnection::createRemoteProcess.
+    The process is started via the start() member function.
+    A closeChannel() function is provided, but rarely useful, because
+
+    \list
+    \i  a) when the process ends, the channel is closed automatically, and
+    \i  b) closing a channel will not necessarily kill the remote process.
+    \endlist
+
+    Therefore, the only sensible use case for calling closeChannel() is to
+    get rid of an SshRemoteProces object before the process is actually started.
+    Note that the process does not have a terminal, so you can't use it
+    for applications that require one.
+ */
+
 namespace Utils {
 
 const QByteArray SshRemoteProcess::AbrtSignal("ABRT");

src/libs/utils/ssh/sshremoteprocess.h

@@ -50,19 +50,6 @@ class SshRemoteProcessPrivate;
 class SshSendFacility;
 } // namespace Internal
 
-
-/*
- * This class implements an SSH channel for running a remote process.
- * Objects are created via SshConnection::createRemoteProcess.
- * The process is started via the start() member function.
- * A closeChannel() function is provided, but rarely useful, because
- *    a) when the process ends, the channel is closed automatically, and
- *    b) closing a channel will not necessarily kill the remote process.
- * Therefore, the only sensible use case for calling closeChannel() is to
- * get rid of an SshRemoteProces object before the process is actually started.
- * Note that the process does not have a terminal, so you can't use it
- * for applications that require one.
- */
 class QTCREATOR_UTILS_EXPORT SshRemoteProcess : public QObject
 {
     Q_OBJECT

src/libs/utils/ssh/sshremoteprocessrunner.cpp

@@ -35,6 +35,12 @@
 
 #define ASSERT_STATE(states) assertState(states, Q_FUNC_INFO)
 
+/*!
+    \class Utils::SshRemoteProcessRunner
+
+    \brief Convenience class for running a remote process over an SSH connection.
+*/
+
 namespace Utils {
 
 class SshRemoteProcessRunnerPrivate : public QObject

src/libs/utils/ssh/sshremoteprocessrunner.h

@@ -40,7 +40,6 @@
 namespace Utils {
 class SshRemoteProcessRunnerPrivate;
 
-// Convenience class for running a remote process over an SSH connection.
 class QTCREATOR_UTILS_EXPORT SshRemoteProcessRunner : public QObject
 {
     Q_OBJECT

src/libs/utils/submiteditorwidget.cpp

@@ -51,6 +51,29 @@ enum { defaultLineWidth = 72 };
 
 enum { checkableColumn = 0 };
 
+/*!
+    \class Utils::SubmitEditorWidget
+
+    \brief Presents a VCS commit message in a text editor and a
+     checkable list of modified files in a list window.
+
+    The user can delete files from the list by unchecking them or diff the selection
+    by doubleclicking. A list model which contains the file in a column
+    specified by fileNameColumn should be set using setFileModel().
+
+    Additionally, standard creator actions  can be registered:
+    Undo/redo will be set up to work with the description editor.
+    Submit will be set up to be enabled according to checkstate.
+    Diff will be set up to trigger diffSelected().
+
+    Note that the actions are connected by signals; in the rare event that there
+    are several instances of the SubmitEditorWidget belonging to the same
+    context active, the actions must be registered/unregistered in the editor
+    change event.
+    Care should be taken to ensure the widget is deleted properly when the
+    editor closes.
+*/
+
 namespace Utils {
 
 // QActionPushButton: A push button tied to an action

src/libs/utils/submiteditorwidget.h

@@ -53,24 +53,6 @@ namespace Utils {
 class SubmitFieldWidget;
 struct SubmitEditorWidgetPrivate;
 
-/* The submit editor presents the commit message in a text editor and an
- * checkable list of modified files in a list window. The user can delete
- * files from the list by unchecking them or diff the selection
- * by doubleclicking. A list model which contains the file in a column
- * specified by fileNameColumn should be set using setFileModel().
- *
- * Additionally, standard creator actions  can be registered:
- * Undo/redo will be set up to work with the description editor.
- * Submit will be set up to be enabled according to checkstate.
- * Diff will be set up to trigger diffSelected().
- *
- * Note that the actions are connected by signals; in the rare event that there
- * are several instances of the SubmitEditorWidget belonging to the same
- * context active, the actions must be registered/unregistered in the editor
- * change event.
- * Care should be taken to ensure the widget is deleted properly when the
- * editor closes. */
-
 class QTCREATOR_UTILS_EXPORT SubmitEditorWidget : public QWidget
 {
     Q_OBJECT

src/libs/utils/submitfieldwidget.cpp

@@ -55,6 +55,18 @@ static void inline setComboBlocked(QComboBox *cb, int index)
     cb->blockSignals(blocked);
 }
 
+/*!
+    \class Utils::SubmitFieldWidget
+    \brief A widget for editing submit message fields like "reviewed-by:",
+    "signed-off-by:".
+
+    It displays them in a vertical row of combo/line edit fields
+    that is modeled after the target address controls of mail clients.
+    When choosing a different field in the combo, a new row is opened if text
+    has been entered for the current field. Optionally, a "Browse..." button and
+    completer can be added.
+*/
+
 namespace Utils {
 
 // Field/Row entry

src/libs/utils/submitfieldwidget.h

@@ -46,12 +46,6 @@ namespace Utils {
 
 struct SubmitFieldWidgetPrivate;
 
-/* A widget for editing submit message fields like "reviewed-by:",
- * "signed-off-by:". It displays them in a vertical row of combo/line edit fields
- * that is modeled after the target address controls of mail clients.
- * When choosing a different field in the combo, a new row is opened if text
- * has been entered for the current field. Optionally, a "Browse..." button and
- * completer can be added. */
 class QTCREATOR_UTILS_EXPORT SubmitFieldWidget : public QWidget
 {
     Q_OBJECT

src/libs/utils/synchronousprocess.cpp

@@ -50,6 +50,37 @@
 #    include <unistd.h>
 #endif
 
+/*!
+    \class Utils::SynchronousProcess
+
+    \brief Runs a synchronous process in its own event loop
+    that blocks only user input events. Thus, it allows for the gui to
+    repaint and append output to log windows.
+
+    The stdOut(), stdErr() signals are emitted unbuffered as the process
+    writes them.
+
+    The stdOutBuffered(), stdErrBuffered() signals are emitted with complete
+    lines based on the '\n' marker if they are enabled using
+    stdOutBufferedSignalsEnabled()/setStdErrBufferedSignalsEnabled().
+    They would typically be used for log windows.
+
+    There is a timeout handling that takes effect after the last data have been
+    read from stdout/stdin (as opposed to waitForFinished(), which measures time
+    since it was invoked). It is thus also suitable for slow processes that continously
+    output data (like version system operations).
+
+    The property timeOutMessageBoxEnabled influences whether a message box is
+    shown asking the user if they want to kill the process on timeout (default: false).
+
+    There are also static utility functions for dealing with fully synchronous
+    processes, like reading the output with correct timeout handling.
+
+    Caution: This class should NOT be used if there is a chance that the process
+    triggers opening dialog boxes (for example, by file watchers triggering),
+    as this will cause event loop problems.
+*/
+
 enum { debug = 0 };
 enum { syncDebug = 0 };
 

src/libs/utils/synchronousprocess.h

@@ -80,26 +80,6 @@ struct QTCREATOR_UTILS_EXPORT SynchronousProcessResponse
 
 QTCREATOR_UTILS_EXPORT QDebug operator<<(QDebug str, const SynchronousProcessResponse &);
 
-/* SynchronousProcess: Runs a synchronous process in its own event loop
- * that blocks only user input events. Thus, it allows for the gui to
- * repaint and append output to log windows.
- *
- * The stdOut(), stdErr() signals are emitted unbuffered as the process
- * writes them.
- *
- * The stdOutBuffered(), stdErrBuffered() signals are emitted with complete
- * lines based on the '\n' marker if they are enabled using
- * stdOutBufferedSignalsEnabled()/setStdErrBufferedSignalsEnabled().
- * They would typically be used for log windows.
- *
- * There is a timeout handling that takes effect after the last data have been
- * read from stdout/stdin (as opposed to waitForFinished(), which measures time
- * since it was invoked). It is thus also suitable for slow processes that continously
- * output data (like version system operations).
- *
- * The property timeOutMessageBoxEnabled influences whether a message box is
- * shown asking the user if they want to kill the process on timeout (default: false). */
-
 class QTCREATOR_UTILS_EXPORT SynchronousProcess : public QObject
 {
     Q_OBJECT

src/libs/utils/treewidgetcolumnstretcher.cpp

@@ -35,8 +35,19 @@
 #include <QtGui/QTreeWidget>
 #include <QtGui/QHideEvent>
 #include <QtGui/QHeaderView>
+
 using namespace Utils;
 
+/*!
+    \class Utils::TreeWidgetColumnStretcher
+
+    \brief The class fixes QTreeWidget to resize all columns to contents, except one
+    stretching column.
+
+    As opposed to standard QTreeWidget, all columns are
+    still interactively resizable.
+*/
+
 TreeWidgetColumnStretcher::TreeWidgetColumnStretcher(QTreeWidget *treeWidget, int columnToStretch)
         : QObject(treeWidget->header()), m_columnToStretch(columnToStretch)
 {

src/libs/utils/treewidgetcolumnstretcher.h

@@ -43,21 +43,13 @@ QT_END_NAMESPACE
 
 namespace Utils {
 
-/*
-
-The class fixes QTreeWidget to resize all columns to contents, except one
-stretching column. As opposed to standard QTreeWidget, all columns are
-still interactively resizable.
-
-*/
-
 class QTCREATOR_UTILS_EXPORT TreeWidgetColumnStretcher : public QObject
 {
-    int m_columnToStretch;
+    const int m_columnToStretch;
 public:
-    TreeWidgetColumnStretcher(QTreeWidget *treeWidget, int columnToStretch);
+    explicit TreeWidgetColumnStretcher(QTreeWidget *treeWidget, int columnToStretch);
 
-    bool eventFilter(QObject *obj, QEvent *ev);
+    virtual bool eventFilter(QObject *obj, QEvent *ev);
 };
 
 } // namespace Utils

src/libs/utils/welcomemodetreewidget.cpp

@@ -46,6 +46,11 @@ enum { leftContentsMargin = 2,
        bottomContentsMargin = 1,
        pixmapWidth = 24 };
 
+/*!
+    \class Utils::WelcomeModeLabel
+    \brief Label usable for headers of a Welcome page.
+*/
+
 namespace Utils {
 
 WelcomeModeLabel::WelcomeModeLabel(QWidget *parent) :
@@ -247,6 +252,11 @@ WelcomeModeTreeWidgetPrivate::WelcomeModeTreeWidgetPrivate() :
     layout->setMargin(0);
 }
 
+/*!
+    \class Utils::WelcomeModeTreeWidget
+    \brief Show an itemized list with arrows and emits a signal on click.
+*/
+
 WelcomeModeTreeWidget::WelcomeModeTreeWidget(QWidget *parent) :
         QWidget(parent), m_d(new WelcomeModeTreeWidgetPrivate)
 {

src/libs/utils/welcomemodetreewidget.h

@@ -44,7 +44,6 @@ namespace Utils {
 struct WelcomeModeTreeWidgetPrivate;
 class WelcomeModeItemWidget;
 
-// Label usable for headers of a Welcome page.
 class QTCREATOR_UTILS_EXPORT WelcomeModeLabel : public QLabel
 {
     Q_OBJECT
@@ -56,7 +55,6 @@ private:
     void *m_unused;
 };
 
-// WelcomeModeTreeWidget: Show an itemized list with arrows and emits a signal on click.
 class QTCREATOR_UTILS_EXPORT WelcomeModeTreeWidget : public QWidget
 {
     Q_OBJECT

src/libs/utils/wizard.cpp

@@ -42,6 +42,13 @@
 #include <QtGui/QHBoxLayout>
 #include <QtGui/QStyle>
 
+/*! \class Utils::Wizard
+
+  \brief A wizard with a progress bar on the left.
+
+  Informs the user about the progress.
+*/
+
 namespace Utils {
 
 class ProgressItemWidget : public QWidget