Doc: edit utils docs

Use \a for all attributes in function descriptions
to avoid QDoc errors. Do not use \param, because
it is not a valid QDoc command.

Do not use \returns as it does not exist.

Do not use \brief for functions. It is not obligatory, so
rather than add them for all functions, let's consistenly leave them out.

Fix typos, grammar and style issues, and punctuation.

Change-Id: Ib8f296f93976265bb93dbeab40c5b47156518122
Reviewed-by: hjk <hjk121@nokiamail.com>

src/libs/utils/bracematcher.cpp

@@ -38,13 +38,13 @@
     and quotes.
 
     This is a helper class for autocompleter implementations. To use it,
-    define "brace", "quote", and "delimiter" characters for given language.
+    define \e brace, \e quote, and \e delimiter characters for a given language.
 */
 
 namespace Utils {
 
 /*!
- * Adds a pair of characters, corresponding to opening and closing braces.
+ * Adds a pair of characters, corresponding to \a opening and \a closing braces.
  */
 void BraceMatcher::addBraceCharPair(const QChar opening, const QChar closing)
 {
@@ -52,7 +52,7 @@ void BraceMatcher::addBraceCharPair(const QChar opening, const QChar closing)
 }
 
 /*!
- * Adds quote character
+ * Adds a \a quote character.
  */
 void BraceMatcher::addQuoteChar(const QChar quote)
 {
@@ -60,8 +60,8 @@ void BraceMatcher::addQuoteChar(const QChar quote)
 }
 
 /*!
- * Adds separator character that should be skipped when overtyping it, e.g.
+ * Adds a separator character \a sep that should be skipped when overtyping it.
- * it could be ';' or ',' in C-like languages.
+ * For example, it could be ';' or ',' in C-like languages.
  */
 void BraceMatcher::addDelimiterChar(const QChar sep)
 {
@@ -113,7 +113,7 @@ QString BraceMatcher::insertMatchingBrace(const QTextCursor &cursor,
 }
 
 /*!
- * Returns true if given character was added as one of character types.
+ * Returns true if the character \a c was added as one of character types.
  */
 bool BraceMatcher::isKnownChar(const QChar c) const
 {

src/libs/utils/completingtextedit.cpp

@@ -44,7 +44,7 @@ static bool isEndOfWordChar(const QChar &c)
   \brief The CompletingTextEdit class is a QTextEdit with auto-completion
   support.
 
-  Excerpted from Qt examples/tools/customcompleter
+  Excerpted from Qt examples/tools/customcompleter.
 */
 
 namespace Utils {

src/libs/utils/fancylineedit.cpp

@@ -41,11 +41,10 @@
 #include <QPropertyAnimation>
 #include <QStyle>
 
-/*! Opens a menu at the specified widget position.
+/*!
- * This functions computes the position where to show the menu, and opens it with
+ * Opens \a menu at the specified \a widget position.
+ * This function computes the position where to show the menu, and opens it with
  * QMenu::exec().
- * \param menu The menu to open
- * \param widget The widget next to which to open the menu
  */
 static void execMenuAtWidget(QMenu *menu, QWidget *widget)
 {

src/libs/utils/fileinprojectfinder.cpp

@@ -44,16 +44,15 @@ namespace Utils {
   \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
+  Often files are copied in the build and deploy process. findFile() searches for an existing file
-  in the project directory for a given file path:
+  in the project directory for a given file path.
 
-  E.g. following file paths:
+  For example, the following file paths should all be mapped to
+  $PROJECTDIR/qml/app/main.qml:
   \list
   \li C:/app-build-desktop/qml/app/main.qml (shadow build directory)
   \li /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()
@@ -110,14 +109,14 @@ void FileInProjectFinder::setSysroot(const QString &sysroot)
     m_cache.clear();
 }
 
-/**
+/*!
-  Returns the best match for the given file url in the project directory.
+  Returns the best match for the given file URL in the project directory.
 
   The method first checks whether the file inside the project directory exists.
   If not, the leading directory in the path is stripped, and the - now shorter - path is
   checked for existence, and so on. Second, it tries to locate the file in the sysroot
   folder specified. Third, we walk the list of project files, and search for a file name match
-  there. If all fails, it returns the original path from the file url.
+  there. If all fails, it returns the original path from the file URL.
   */
 QString FileInProjectFinder::findFile(const QUrl &fileUrl, bool *success) const
 {

src/libs/utils/filesystemwatcher.cpp

@@ -163,7 +163,7 @@ bool FileSystemWatcherPrivate::checkLimit() const
 }
 
 /*!
-    \brief Add to watcher 0.
+    Adds directories to watcher 0.
 */
 
 FileSystemWatcher::FileSystemWatcher(QObject *parent) :
@@ -173,7 +173,7 @@ FileSystemWatcher::FileSystemWatcher(QObject *parent) :
 }
 
 /*!
-    \brief Add to a watcher with specified id.
+    Adds directories to a watcher with the specified \a id.
 */
 
 FileSystemWatcher::FileSystemWatcher(int id, QObject *parent) :

src/libs/utils/fileutils.cpp

@@ -52,7 +52,7 @@ namespace Utils {
 
   \note The \a error parameter is optional.
 
-  \return Whether the operation succeeded.
+  Returns whether the operation succeeded.
 */
 bool FileUtils::removeRecursively(const FileName &filePath, QString *error)
 {
@@ -118,7 +118,7 @@ bool FileUtils::removeRecursively(const FileName &filePath, QString *error)
 
   \note The \a error parameter is optional.
 
-  \return Whether the operation succeeded.
+  Returns whether the operation succeeded.
 */
 bool FileUtils::copyRecursively(const FileName &srcFilePath, const FileName &tgtFilePath,
                                 QString *error)
@@ -162,7 +162,8 @@ bool FileUtils::copyRecursively(const FileName &srcFilePath, const FileName &tgt
   true if one of them is newer than \a timeStamp. If \a filePath is a single file, true will
   be returned if the file is newer than \timeStamp.
 
-  \return Whether at least one file in \a filePath has a newer date than \a timeStamp.
+  Returns whether at least one file in \a filePath has a newer date than
+  \a timeStamp.
 */
 bool FileUtils::isFileNewerThan(const FileName &filePath, const QDateTime &timeStamp)
 {
@@ -181,13 +182,13 @@ bool FileUtils::isFileNewerThan(const FileName &filePath, const QDateTime &timeS
 }
 
 /*!
-  Recursively resolve possibly present symlinks in \a filePath.
+  Recursively resolves possibly present symlinks in \a filePath.
   Unlike QFileInfo::canonicalFilePath(), this function will still return the expected target file
   even if the symlink is dangling.
 
   \note Maximum recursion depth == 16.
 
-  return Symlink target file path.
+  Returns the symlink target file path.
 */
 FileName FileUtils::resolveSymlinks(const FileName &path)
 {
@@ -204,7 +205,7 @@ FileName FileUtils::resolveSymlinks(const FileName &path)
   Like QDir::toNativeSeparators(), but use prefix '~' instead of $HOME on unix systems when an
   absolute path is given.
 
-  return Possibly shortened path with native separators.
+  Returns the possibly shortened path with native separators.
 */
 QString FileUtils::shortNativePath(const FileName &path)
 {

src/libs/utils/json.cpp

@@ -303,11 +303,12 @@ void JsonSchema::enterNestedPropertySchema(const QString &property)
 }
 
 /*!
- * An array schema is allowed to have its *items* specification in the form of another schema
+ * An array schema is allowed to have its \e items specification in the form of
+ * another schema
  * or in the form of an array of schemas [Sec. 5.5]. This methods checks whether this is case
  * in which the items are a schema.
  *
- * \return whether or not the items from the array are a schema
+ * Returns whether or not the items from the array are a schema.
  */
 bool JsonSchema::hasItemSchema() const
 {
@@ -324,11 +325,11 @@ void JsonSchema::enterNestedItemSchema()
 }
 
 /*!
- * An array schema is allowed to have its *items* specification in the form of another schema
+ * An array schema is allowed to have its \e items specification in the form of another schema
  * or in the form of an array of schemas [Sec. 5.5]. This methods checks whether this is case
  * in which the items are an array of schemas.
  *
- * \return whether or not the items from the array are a an array of schemas
+ * Returns whether or not the items from the array are a an array of schemas.
  */
 bool JsonSchema::hasItemArraySchema() const
 {
@@ -345,14 +346,16 @@ int JsonSchema::itemArraySchemaSize() const
 }
 
 /*!
- * When evaluating the items of an array it might be necessary to "enter" a particular schema,
+ * When evaluating the items of an array it might be necessary to \e enter a
+ * particular schema,
  * since this API assumes that there's always a valid schema in context (the one the user is
  * interested on). This shall only happen if the item at the supplied array index is of type
  * object, which is then assumed to be a schema.
  *
  * The method also marks the context as being inside an array evaluation.
  *
- * \return whether it was necessary to "enter" a schema for the supplied array index, false if index is out of bounds
+ * Returns whether it was necessary to enter a schema for the supplied
+ * array \a index, false if index is out of bounds.
  */
 bool JsonSchema::maybeEnterNestedArraySchema(int index)
 {
@@ -369,7 +372,7 @@ bool JsonSchema::maybeEnterNestedArraySchema(int index)
  * array of allowed types for the particular instance [Sec. 5.1]. This method checks whether
  * the current schema is one of such.
  *
- * \return whether or not the current schema specifies a union type
+ * Returns whether or not the current schema specifies a union type.
  */
 bool JsonSchema::hasUnionSchema() const
 {
@@ -382,15 +385,16 @@ int JsonSchema::unionSchemaSize() const
 }
 
 /*!
- * When evaluating union types it might be necessary to "enter" a particular schema, since this
+ * When evaluating union types it might be necessary to enter a particular
+ * schema, since this
  * API assumes that there's always a valid schema in context (the one the user is interested on).
- * This shall only happen if the item at the supplied union index, which is then assumed to be
+ * This shall only happen if the item at the supplied union \a index, which is then assumed to be
  * a schema.
  *
  * The method also marks the context as being inside an union evaluation.
  *
- * \param index
+ * Returns whether or not it was necessary to enter a schema for the
- * \return whether or not it was necessary to "enter" a schema for the supplied union index
+ * supplied union index.
  */
 bool JsonSchema::maybeEnterNestedUnionSchema(int index)
 {
@@ -673,16 +677,13 @@ JsonSchemaManager::~JsonSchemaManager()
 }
 
 /*!
- * \brief JsonManager::schemaForFile
+ * Tries to find a JSON schema to validate \a fileName against. According
- *
- * Try to find a JSON schema to which the supplied file can be validated against. According
  * to the specification, how the schema/instance association is done is implementation defined.
  * Currently we use a quite naive approach which is simply based on file names. Specifically,
  * if one opens a foo.json file we'll look for a schema named foo.json. We should probably
  * investigate alternative settings later.
  *
- * \param fileName - JSON file to be validated
+ * Returns a valid schema or 0.
- * \return a valid schema or 0
  */
 JsonSchema *JsonSchemaManager::schemaForFile(const QString &fileName) const
 {

src/libs/utils/networkaccessmanager.cpp

@@ -43,7 +43,7 @@
     \brief The NetworkManager class provides a network access manager for use
     with \QC.
 
-   Common initialization, Qt Creator User Agent
+   Common initialization, \QC User Agent.
 
    Preferably, the instance returned by NetworkAccessManager::instance() should be used for the main
    thread. The constructor is provided only for multithreaded use.

src/libs/utils/pathchooser.cpp

@@ -50,7 +50,7 @@
     consisting of a QLineEdit and
     a "Browse" button.
 
-    Has some validation logic for embedding into QWizardPage.
+    This class has some validation logic for embedding into QWizardPage.
 */
 
 const char * const Utils::PathChooser::browseButtonLabel =

src/libs/utils/projectintropage.cpp

@@ -42,13 +42,13 @@
     Looks similar to FileWizardPage, but provides additional
     functionality:
     \list
-    \li Description label at the top for displaying introductory text
+    \li Contains a description label at the top for displaying introductory text.
-    \li It does on the fly validation (connected to changed()) and displays
+    \li Does on the fly validation (connected to changed()) and displays
-       warnings/errors in a status label at the bottom (the page is complete
+       warnings and 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
+    \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.

src/libs/utils/qtcprocess.cpp

@@ -200,14 +200,14 @@ static QStringList doSplitArgs(const QString &args, QtcProcess::SplitError *err)
 }
 
 /*!
-    Splits \a args according to system shell word splitting and quoting rules.
+    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
-    \li Whitespace splits tokens
+    \li Whitespace splits tokens.
-    \li The backslash quotes the following character
+    \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,
@@ -219,17 +219,25 @@ static QStringList doSplitArgs(const QString &args, QtcProcess::SplitError *err)
     If \a abortOnMeta is \c true, encounters of unhandled meta characters are
     treated as errors.
 
+    If \a err is not NULL, stores a status code at the pointer target. For more
+    information, see \l SplitError.
+
+    If \env is not NULL, performs variable substitution with the
+    given environment.
+
+    Returns a list of unquoted words or an empty list if an error occurred.
+
     \section1 Windows
 
     The behavior is defined by the Microsoft C runtime:
     \list
-    \li Whitespace splits tokens
+    \li Whitespace splits tokens.
-    \li A string enclosed in double quotes is not split
+    \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:
+    \li Backslashes have special semantics if 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
@@ -248,14 +256,6 @@ static QStringList doSplitArgs(const QString &args, QtcProcess::SplitError *err)
     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 \l 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,

src/libs/utils/tcpportsgatherer.cpp

@@ -250,7 +250,8 @@ void TcpPortsGathererPrivate::updateNetstat()
     \brief The TcpPortsGatherer class gathers the list of local TCP ports
     already in use.
 
-  Query the system for the list of local TCP ports already in use. This information can be used
+    Queries the system for the list of local TCP ports already in use. This
+    information can be used
   to select a port for use in a range.
 */
 
@@ -283,7 +284,7 @@ QList<int> TcpPortsGatherer::usedPorts() const
 }
 
 /*!
-  Select a port out of \a freePorts that is not yet used.
+  Selects a port out of \a freePorts that is not yet used.
 
   Returns the port, or -1 if no free port is available.
   */

src/libs/utils/textfileformat.cpp

@@ -78,7 +78,7 @@ TextFileFormat::TextFileFormat() :
 }
 
 /*!
-    \brief Detect the format of text data.
+    Detects the format of text data.
 */
 
 TextFileFormat TextFileFormat::detect(const QByteArray &data)
@@ -111,7 +111,7 @@ TextFileFormat TextFileFormat::detect(const QByteArray &data)
 }
 
 /*!
-    \brief Returns a piece of text suitable as display for a encoding error.
+    Returns a piece of text suitable as display for a encoding error.
 */
 
 QByteArray TextFileFormat::decodingErrorSample(const QByteArray &data)
@@ -179,7 +179,7 @@ bool decodeTextFileContent(const QByteArray &dataBA,
 }
 
 /*!
-    \brief Decode data to a plain string.
+    Decodes data to a plain string.
 */
 
 bool TextFileFormat::decode(const QByteArray &data, QString *target) const
@@ -189,7 +189,7 @@ bool TextFileFormat::decode(const QByteArray &data, QString *target) const
 }
 
 /*!
-    \brief Decode data to a list of strings.
+    Decodes data to a list of strings.
 
     Intended for use with progress bars loading large files.
 */
@@ -236,7 +236,7 @@ TextFileFormat::ReadResult readTextFile(const QString &fileName, const QTextCode
 }
 
 /*!
-    \brief Read text file into a list of strings.
+    Reads a text file into a list of strings.
 */
 
 TextFileFormat::ReadResult
@@ -254,7 +254,7 @@ TextFileFormat::ReadResult
 }
 
 /*!
-    \brief Read text file into a string.
+    Reads a text file into a string.
 */
 
 TextFileFormat::ReadResult
@@ -272,7 +272,7 @@ TextFileFormat::ReadResult
 }
 
 /*!
-    \brief Write out a text file.
+    Writes out a text file.
 */
 
 bool TextFileFormat::writeFile(const QString &fileName, QString plainText, QString *errorString) const

src/libs/zeroconf/servicebrowser.cpp

@@ -395,7 +395,7 @@ QDebug operator<<(QDebug dbg, const Service::ConstPtr &service){
 /*!
   \fn bool Service::outdated() const
 
-  Returns if the service data is outdated, its value might change even on
+  Returns whether the service data is outdated. Its value might change even on
   the (otherwise constant) objects returned by a ServiceBrowser.
 */
 /*!
@@ -421,7 +421,7 @@ QDebug operator<<(QDebug dbg, const Service::ConstPtr &service){
 /*!
   \fn QString Service::port() const
 
-  Return the port of the service (as a string, not as number).
+  Returns the port of the service (as a string, not as number).
 */
 /*!
   \fn const Service::ServiceTxtRecord &txtRecord() const
@@ -436,7 +436,8 @@ QDebug operator<<(QDebug dbg, const Service::ConstPtr &service){
 /*!
   \fn int Service::interfaceNr() const
 
-  returns the interface on which the service is reachable, 1 based, 0 means to try all interfaces
+    Returns the interface on which the service is reachable, 1 based, 0 means to
+    try all interfaces.
 */
 /*!
   \fn bool Service::invalidate()
@@ -452,7 +453,7 @@ QDebug operator<<(QDebug dbg, const Service::ConstPtr &service){
   service.
 
   The actual browsing starts only when startBrowsing() is called. If you want to receive all service
-  changes connect before starting browsing.
+  changes, connect before starting browsing.
 
   The current list of services can be gathered with the services() method.
 
@@ -573,23 +574,23 @@ void ServiceBrowser::autoRefresh()
   \fn void ServiceBrowser::serviceChanged(
        Service::ConstPtr oldService, Service::ConstPtr newService, ServiceBrowser *browser)
 
-   This signal is called when a service is added removed or changes.
+   This signal is called when a service is added, removed, or changed.
    Both oldService or newService might be null (covers both add and remove).
    The services list might not be synchronized with respect to this signal.
 */
 /*!
   \fn void ServiceBrowser::serviceAdded(Service::ConstPtr service, ServiceBrowser *browser)
 
-   This signal is called when a service is added (convenience method)
+   This signal is called when a service is added (convenience method).
-   the services list might not be synchronized with respect to this signal
+   The services list might not be synchronized with respect to this signal.
 
    \sa serviceChanged()
 */
 /*!
   \fn void ServiceBrowser::serviceRemoved(Service::ConstPtr service, ServiceBrowser *browser)
 
-  This signal is called when a service is removed (convenience method)
+  This signal is called when a service is removed (convenience method).
-  the services list might not be synchronized with respect to this signal
+  The services list might not be synchronized with respect to this signal.
 
    \sa serviceChanged()
 */
@@ -597,8 +598,9 @@ void ServiceBrowser::autoRefresh()
   \fn void ServiceBrowser::servicesUpdated(ServiceBrowser *browser)
 
   This signal is called when the list is updated.
-  It might collect several serviceChanged signals together, if you use the list returned by
+  It might collect several serviceChanged signals together. If you use the list
-  services(), use this signal, not serviceChanged(), serviceAdded() or serviceRemoved() to know
+  returned by services(), use this signal, not serviceChanged(), serviceAdded(),
+  or serviceRemoved() to learn
   about changes to the list.
 */
 /*!