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)
-      C:/Private/e3026d63/qml/app/main.qml  (Application data folder on Symbian device)
-      /Users/x/app-build-desktop/App.app/Contents/Resources/qml/App/main.qml (folder on Mac OS X)
- should all be mapped to
-      $PROJECTDIR/qml/app/main.qml
-  */
+  \list
+  \i C:/app-build-desktop/qml/app/main.qml (shadow build directory)
+  \i C:/Private/e3026d63/qml/app/main.qml  (Application data folder on Symbian device)
+  \i /Users/x/app-build-desktop/App.app/Contents/Resources/qml/App/main.qml (folder on Mac OS X)
+  \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
-    // If these icons are not avaiable we use the freedesktop standard name before
-    // falling back to a bundled resource
+    // KDE has custom icons for this. Notice that icon namings are counter intuitive.
+    // If these icons are not available we use the freedesktop standard name before
+    // 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