Commit 41411165 authored by Leena Miettinen's avatar Leena Miettinen

Doc: use standard wording in \brief commands

QDoc does some magic with the \class and \namespaces
and \brief commands, so the following wording must be used:
"The xxx class yyy ..."

Change-Id: Id231f30e8464898b776888d5423523de404aae34
Reviewed-by: default avatarEike Ziller <eike.ziller@digia.com>
parent 44072532
......@@ -48,7 +48,8 @@
\mainclass
\threadsafe
\brief Defines a collection of related components that can be viewed as a unit.
\brief The Aggregate class defines a collection of related components that
can be viewed as a unit.
An Aggregate is a collection of components that are handled as a unit,
such that each component exposes the properties and behavior of the
......
......@@ -381,13 +381,15 @@ void Document::addUndefinedMacroUse(const QByteArray &name, unsigned offset)
/*!
\class Document::MacroUse
\brief Represents the usage of a macro in a \l {Document}.
\brief The MacroUse class represents the usage of a macro in a
\l {Document}.
\sa Document::UndefinedMacroUse
*/
/*!
\class Document::UndefinedMacroUse
\brief Represents a macro that was looked up, but not found.
\brief The UndefinedMacroUse class represents a macro that was looked for,
but not found.
Holds data about the reference to a macro in an \tt{#ifdef} or \tt{#ifndef}
or argument to the \tt{defined} operator inside an \tt{#if} or \tt{#elif} that does
......
......@@ -33,7 +33,8 @@ using namespace CPlusPlus;
/*!
\class Client
\brief A notification interface for for C++ preprocessor.
\brief The Client class implements a notification interface for the
C++ preprocessor.
*/
/*!
......
......@@ -35,7 +35,7 @@
/*!
\class ExtensionSystem::IPlugin
\mainclass
\brief Base class for all plugins.
\brief The IPlugin class is the base class for all plugins.
The IPlugin class is an abstract class that must be implemented
once for each plugin.
......
......@@ -35,7 +35,8 @@
/*!
\class ExtensionSystem::PluginDetailsView
\brief Widget that displays the contents of a PluginSpec.
\brief The PluginDetailsView class implements a widget that displays the
contents of a PluginSpec.
Can be used for integration in the application that
uses the plugin manager.
......
......@@ -35,7 +35,8 @@
/*!
\class ExtensionSystem::PluginErrorView
\brief Widget that displays the state and error message of a PluginSpec.
\brief The PluginErrorView class implements a widget that displays the
state and error message of a PluginSpec.
Can be used for integration in the application that
uses the plugin manager.
......
......@@ -76,7 +76,8 @@ enum { debugLeaks = 0 };
\class ExtensionSystem::PluginManager
\mainclass
\brief Core plugin system that manages the plugins, their life cycle and their registered objects.
\brief The PluginManager class implements the core plugin system that
manages the plugins, their life cycle, and their registered objects.
The plugin manager is used for the following tasks:
\list
......
......@@ -63,7 +63,8 @@
/*!
\class ExtensionSystem::PluginDependency
\brief Struct that contains the name and required compatible version number of a plugin's dependency.
\brief The PluginDependency class contains the name and required compatible
version number of a plugin's dependency.
This reflects the data of a dependency tag in the plugin's xml description file.
The name and version are used to resolve the dependency, i.e. a plugin with the given name and
......@@ -102,7 +103,8 @@
/*!
\class ExtensionSystem::PluginSpec
\brief Contains the information of the plugins xml description file and
\brief The PluginSpec class contains the information of the plugin's XML
description file and
information about the plugin's current state.
The plugin spec is also filled with more information as the plugin
......
......@@ -42,7 +42,8 @@
/*!
\class ExtensionSystem::PluginView
\brief Widget that shows a list of all plugins and their state.
\brief The PluginView class implements a widget that shows a list of all
plugins and their state.
This can be embedded e.g. in a dialog in the application that
uses the plugin manager.
......
......@@ -30,7 +30,8 @@
/*!
\class QmlJS::PersistentTrie::Trie
\brief Implements a trie that is persistent (not on disk but in memory).
\brief The Trie class implements a trie that is
persistent (not on disk but in memory).
This means that several versions can coexist, as adding an element
is non destructive, and as much as possible is shared.
......
......@@ -41,7 +41,7 @@ using namespace QmlJS::AST;
/*!
\class QmlJS::Bind
\brief Collected information about a single Document.
\brief The Bind class collects information about a single Document.
\sa Document Context
Each Document owns an instance of Bind. It provides access to data
......
......@@ -36,7 +36,8 @@ using namespace QmlJS::AST;
/*!
\class QmlJS::Context
\brief Holds information about relationships between documents in a Snapshot.
\brief The Context class holds information about relationships between
documents in a Snapshot.
\sa Document Link Snapshot
Contexts are usually created through Link. Once created, a Context is immutable
......
......@@ -39,7 +39,7 @@ using namespace QmlJS::AST;
/*!
\class QmlJS::Document
\brief A Qml or JavaScript document.
\brief The Document class creates a QML or JavaScript document.
\sa Snapshot
Documents are usually created by the ModelManagerInterface
......@@ -57,7 +57,7 @@ using namespace QmlJS::AST;
/*!
\class QmlJS::LibraryInfo
\brief A Qml library.
\brief The LibraryInfo class creates a QML library.
\sa Snapshot
A LibraryInfo is created when the ModelManagerInterface finds
......@@ -71,11 +71,10 @@ using namespace QmlJS::AST;
/*!
\class QmlJS::Snapshot
\brief A set of Document::Ptr and LibraryInfo instances.
\brief The Snapshot class holds and offers access to a set of
Document::Ptr and LibraryInfo instances.
\sa Document LibraryInfo
A Snapshot holds and offers access to a set of Document and LibraryInfo instances.
Usually Snapshots are copies of the snapshot maintained and updated by the
ModelManagerInterface that updates its instance as parsing
threads finish and new information becomes available.
......
......@@ -37,7 +37,7 @@ using namespace QmlJS;
/*!
\class QmlJS::Evaluate
\brief Evaluates \l{AST::Node}s to \l{Value}s.
\brief The Evaluate class evaluates \l{AST::Node}s to \l{Value}s.
\sa Value ScopeChain
The Evaluate visitor is constructed with a ScopeChain and accepts JavaScript
......
......@@ -53,7 +53,8 @@ using namespace QmlJS::AST;
/*!
\class QmlJS::Value
\brief Abstract base class for the result of a JS expression.
\brief The Value class is an abstract base class for the result of a
JS expression.
\sa Evaluate ValueOwner ValueVisitor
A Value represents a category of JavaScript values, such as number
......
......@@ -122,7 +122,7 @@ public:
/*!
\class QmlJS::Link
\brief Creates a Context for a Snapshot.
\brief The Link class creates a Context for a Snapshot.
\sa Context Snapshot
Initializes a context by resolving imports. This is an expensive operation.
......
......@@ -33,7 +33,8 @@ using namespace QmlJS;
/*!
\class QmlJS::ModelManagerInterface
\brief Interface to the global state of the QmlJS code model.
\brief The ModelManagerInterface class acts as an interface to the
global state of the QmlJS code model.
\sa QmlJS::Document QmlJS::Snapshot QmlJSTools::Internal::ModelManager
The ModelManagerInterface is an interface for global state and actions in
......
......@@ -36,7 +36,8 @@ using namespace QmlJS;
/*!
\class QmlJS::ScopeChain
\brief Describes the scopes used for global lookup in a specific location.
\brief The ScopeChain class describes the scopes used for global lookup in
a specific location.
\sa Document Context ScopeBuilder
A ScopeChain is used to perform global lookup with the lookup() method and
......
......@@ -35,7 +35,7 @@ using namespace QmlJS;
/*!
\class QmlJS::ValueOwner
\brief Manages the lifetime of \l{QmlJS::Value}s.
\brief The ValueOwner class manages the lifetime of \l{QmlJS::Value}s.
\sa QmlJS::Value
Values are usually created on a ValueOwner. When the ValueOwner is destroyed
......
......@@ -29,8 +29,8 @@
/*!
\class QRangeModel
\brief The QRangeModel class, helps users to build components that depend
on some value and/or position to be in a certain range previously defined
\brief The QRangeModel class helps users to build components that depend
on some value and/or position to be in a certain range previously defined.
With this class, the user sets a value range and a position range, which
represent the valid values/positions the model can assume. It is worth telling
......
......@@ -46,7 +46,9 @@ enum { debug = 0 };
// ------------- SymbolGroup
/*!
\class SymbolGroup A symbol group storing a tree of expanded symbols rooted on a fake "locals" root element.
\class SymbolGroup
\brief The SymbolGroup class creates a symbol group storing a tree of
expanded symbols rooted on a fake "locals" root element.
Provides a find() method based on inames ("locals.this.i1.data") and
dump() methods used for GDBMI-format dumping and debug helpers.
......@@ -533,8 +535,10 @@ AbstractSymbolGroupNode *SymbolGroup::find(const std::string &iname) const
/*!
\class LocalsSymbolGroup
\brief The LocalsSymbolGroup class creates a Symbol group representing the
Locals view.
Symbol group representing the Locals view. It is firmly associated
It is firmly associated
with stack frame, function (module) and thread.
\ingroup qtcreatorcdbext
*/
......@@ -624,7 +628,9 @@ std::string LocalsSymbolGroup::module() const
/*!
\class WatchesSymbolGroup
Watch symbol group. Contains watches as added by Qt Creator as iname='watch.0',
\brief The WatchesSymbolGroup class creates a watch symbol group.
Contains watches as added by \QC as iname='watch.0',
name='<expression>'. The IDebugSymbolGroup is created without scope.
\ingroup qtcreatorcdbext
*/
......
......@@ -90,7 +90,8 @@ inline std::ostream &operator<<(std::ostream &str, const DebugNodeFlags &f)
/*!
\class AbstractSymbolGroupNode
Abstract base class for a node of SymbolGroup providing the child list interface.
\brief The AbstractSymbolGroupNode class is an abstract base class for a
node of SymbolGroup providing the child list interface.
\ingroup qtcreatorcdbext
*/
AbstractSymbolGroupNode::AbstractSymbolGroupNode(const std::string &name,
......@@ -207,7 +208,8 @@ void AbstractSymbolGroupNode::setParent(AbstractSymbolGroupNode *n)
/*! \class BaseSymbolGroupNode
Base class for a node of SymbolGroup with a flat list of children.
\brief The BaseSymbolGroupNode class is the base class for a node of
SymbolGroup with a flat list of children.
\ingroup qtcreatorcdbext
*/
......@@ -276,9 +278,11 @@ std::ostream &operator<<(std::ostream &str, const DEBUG_SYMBOL_PARAMETERS &param
return str;
}
/*! \struct DumpParameters
/*!
\class DumpParameters
All parameters for GDBMI dumping of a symbol group in one struct.
\brief The DumpParameters class contains all parameters for GDBMI dumping
of a symbol group in one class.
The debugging engine passes maps of type names/inames to special
integer values indicating hex/dec, etc.
\ingroup qtcreatorcdbext
......@@ -580,7 +584,8 @@ void ErrorSymbolGroupNode::debug(std::ostream &os, const std::string &visitingFu
/*! \class SymbolGroupNode
\brief 'Real' node within a symbol group, identified by its index in IDebugSymbolGroup.
\brief The SymbolGroupNode class represents a \e real node within a symbol
group, identified by its index in IDebugSymbolGroup.
Provides accessors for fixed-up symbol group value and a dumping facility
consisting of:
......@@ -1472,8 +1477,11 @@ static inline StringStringPair arrayIndexNameIname(int index)
/*! \class ReferenceSymbolGroupNode
Artificial node referencing another (real) SymbolGroupNode (added symbol or
symbol from within an expanded linked list structure). Forwards the
\brief The ReferenceSymbolGroupNode class is an artificial node referencing
another (real) SymbolGroupNode (added symbol or symbol from within an
expanded linked list structure).
Forwards the
dumping to the referenced node using its own name.
\ingroup qtcreatorcdbext */
......@@ -1509,7 +1517,8 @@ void ReferenceSymbolGroupNode::debug(std::ostream &str, const std::string &visit
/*! \class MapNodeSymbolGroupNode
\brief A [fake] map node with a fake array index and key/value entries consisting
\brief The MapNodeSymbolGroupNode class is a [fake] map node with a fake
array index and key/value entries consisting
of ReferenceSymbolGroupNode.
\ingroup qtcreatorcdbext
*/
......@@ -1559,9 +1568,11 @@ void MapNodeSymbolGroupNode::debug(std::ostream &os, const std::string &visiting
/*! \class SymbolGroupNodeVisitor
Visitor that takes care of iterating over the nodes and
building the full iname path ('local.foo.bar') that is required for
GDBMI dumping. The full name depends on the path on which a node was reached
\brief The SymbolGroupNodeVisitor class is a visitor that iterates over the
nodes and builds the full iname path ('local.foo.bar') that is required for
GDBMI dumping.
The full name depends on the path on which a node was reached
for referenced nodes (a linked list element can be reached via array index
or by expanding the whole structure).
visit() is not called for the (invisible) root node, but starting with the
......@@ -1578,7 +1589,7 @@ std::string SymbolGroupNodeVisitor::parentIname(const std::string &iname)
}
/*! \class DebugSymbolGroupNodeVisitor
\brief Debug output visitor.
\brief The DebugSymbolGroupNodeVisitor class is a debug output visitor.
\ingroup qtcreatorcdbext
*/
......@@ -1597,7 +1608,8 @@ SymbolGroupNodeVisitor::VisitResult
}
/*! \class DebugFilterSymbolGroupNodeVisitor
\brief Debug filtering output visitor.
\brief The DebugFilterSymbolGroupNodeVisitor class is a debug filtering
output visitor.
\ingroup qtcreatorcdbext
*/
......@@ -1620,9 +1632,9 @@ SymbolGroupNodeVisitor::VisitResult
}
/*! \class DumpSymbolGroupNodeVisitor
GDBMI dump output visitor used to report locals values back to the
debugging engine. \ingroup qtcreatorcdbext
\brief The DumpSymbolGroupNodeVisitor class is a GDBMI dump output visitor
used to report locals values back to the debugging engine.
\ingroup qtcreatorcdbext
*/
DumpSymbolGroupNodeVisitor::DumpSymbolGroupNodeVisitor(std::ostream &os,
......
......@@ -47,15 +47,18 @@
typedef std::vector<int>::size_type VectorIndexType;
/*! \struct SymbolGroupValueContext
\brief Structure to pass all IDebug interfaces required for SymbolGroupValue
/*!
\class SymbolGroupValueContext
\brief The SymbolGroupValueContext class passes all IDebug interfaces
required for SymbolGroupValue.
\ingroup qtcreatorcdbext */
/*! \class SymbolGroupValue
Flyweight tied to a SymbolGroupNode
\brief The SymbolGroupValue class is a flyweight tied to a SymbolGroupNode
providing a convenient operator[] (name, index) and value
getters for notation of dumpers.
Inaccessible members return a SymbolGroupValue in state 'invalid'.
Example:
\code
......@@ -681,9 +684,12 @@ static inline std::string resolveQtSymbol(const char *symbolC,
return rc;
}
/*! \struct QtInfo
/*!
\class QtInfo
\brief The QtInfo class provides Qt information determined on demand.
Qt Information determined on demand: Namespace, modules and basic class
Namespace, modules, and basic class
names containing the module for fast lookup.
\ingroup qtcreatorcdbext */
......
......@@ -40,7 +40,7 @@
/*!
\class QSsh::SftpChannel
\brief This class provides SFTP operations.
\brief The SftpChannel class provides SFTP operations.
Objects are created via SshConnection::createSftpChannel().
The channel needs to be initialized with
......
......@@ -51,7 +51,8 @@
/*!
\class QSsh::SshConnection
\brief This class provides an SSH connection, implementing protocol version 2.0
\brief The SshConnection 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.
......
......@@ -43,7 +43,8 @@
/*!
\class QSsh::SshRemoteProcess
\brief This class implements an SSH channel for running a remote process.
\brief The SshRemoteProcess 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.
......
......@@ -36,7 +36,8 @@
/*!
\class QSsh::SshRemoteProcessRunner
\brief Convenience class for running a remote process over an SSH connection.
\brief The SshRemoteProcessRunner class is a convenience class for
running a remote process over an SSH connection.
*/
namespace QSsh {
......
......@@ -40,7 +40,8 @@ enum { debug = 0 };
/*! \class Utils::BaseValidatingLineEdit
\brief Base class for line edits that perform validation.
\brief The BaseValidatingLineEdit class is the base class for line edits
that perform validation.
Performs validation in a virtual validate() function to be implemented in
derived classes.
......
......@@ -34,7 +34,8 @@
/*!
\class Utils::BraceMatcher
\brief Generic autocompleter of braces and quotes.
\brief The BraceMatcher class implements a generic autocompleter of braces
and quotes.
This is a helper class for autocompleter implementations. To use it,
define "brace", "quote", and "delimiter" characters for given language.
......
......@@ -38,7 +38,8 @@
/*!
\class Utils::CheckableMessageBox
\brief A messagebox suitable for questions with a
\brief The CheckableMessageBox class implements a message box suitable for
questions with a
"Do not ask me again" checkbox.
Emulates the QMessageBox API with
......
......@@ -37,7 +37,8 @@
/*!
\class Utils::ClassNameValidatingLineEdit
\brief A Line edit that validates a C++ class name and emits a signal
\brief The ClassNameValidatingLineEdit class implements a line edit that
validates a C++ class name and emits a signal
to derive suggested file names from it.
*/
......
......@@ -41,7 +41,8 @@ static bool isEndOfWordChar(const QChar &c)
/*! \class Utils::CompletingTextEdit
\brief A QTextEdit with auto-completion support
\brief The CompletingTextEdit class is a QTextEdit with auto-completion
support.
Excerpted from Qt examples/tools/customcompleter
*/
......
......@@ -41,7 +41,8 @@
/*!
\class Utils::DetailsWidget
\brief Widget a button to expand a 'Details' area.
\brief The DetailsWidget class implements a button to expand a \e Details
area.
This widget is using a grid layout and places the items
in the following way:
......
......@@ -35,7 +35,8 @@
/*!
\class Utils::ElidingLabel
\brief A label suitable for displaying elided text.
\brief The ElidingLabel class is a label suitable for displaying elided
text.
*/
namespace Utils {
......
......@@ -35,7 +35,7 @@
/*!
\class Utils::FakeToolTip
\brief A widget that pretends to be a tooltip.
\brief The FakeToolTip class is a widget that pretends to be a tooltip.
By default it has Qt::WA_DeleteOnClose set.
*/
......
......@@ -72,7 +72,8 @@ static void execMenuAtWidget(QMenu *menu, QWidget *widget)
/*!
\class Utils::FancyLineEdit
\brief A line edit with an embedded pixmap on one side that is connected to
\brief The FancyLineEdit class is 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")
......
......@@ -45,7 +45,8 @@ namespace Utils {
/*! \class Utils::FancyMainWindow
\brief MainWindow with dock widgets and additional "lock" functionality
\brief The FancyMainWindow class is a 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
......
......@@ -41,7 +41,8 @@ namespace Utils {
/*!
\class Utils::FileInProjectFinder
\brief Helper class to find the 'original' file in the project directory for a given file url.
\brief The FileInProjectFinder class is a helper class to find the \e original
file in the project directory for a given file URL.
Often files are copied in the build + deploy process. findFile() searches for an existing file
in the project directory for a given file path:
......
......@@ -36,7 +36,10 @@
/*!
\class Utils::FileNameValidatingLineEdit
\brief A control that let's the user choose a (base) file name, based on a QLineEdit. Has
\brief The FileNameValidatingLineEdit class is a control that lets the user
choose a (base) file name, based on a QLineEdit.
The class has
some validation logic for embedding into QWizardPage.
*/
......
......@@ -52,7 +52,8 @@ static inline quint64 getFileLimit()
/*!
\class Utils::FileSystemWatcher
\brief File watcher that internally uses a centralized QFileSystemWatcher
\brief The FileSystemWatcher class is a file watcher that internally uses
a centralized QFileSystemWatcher
and enforces limits on Mac OS.
\section1 Design Considerations
......
......@@ -42,9 +42,9 @@ namespace Utils {
/*! \class Utils::FileUtils
\brief File- and directory-related convenience functions.
\brief The FileUtils class contains file and directory related convenience
functions.
File- and directory-related convenience functions.
*/
/*!
......@@ -411,7 +411,7 @@ TempFileSaver::~TempFileSaver()
/*! \class Utils::FileName
\brief A light-weight convenience class for filenames
\brief The FileName class is a light-weight convenience class for filenames.
On windows filenames are compared case insensitively.
*/
......
......@@ -37,8 +37,10 @@
/*!
\class Utils::FileWizardDialog
\brief Standard wizard for a single file letting the user choose name