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) :