Commit efbecf21 authored by Leena Miettinen's avatar Leena Miettinen
Browse files

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: default avatarhjk <hjk121@nokiamail.com>
parent 5358ffe9
......@@ -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.
* it could be ';' or ',' in C-like languages.
* Adds a separator character \a sep that should be skipped when overtyping it.
* 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
{
......
......@@ -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 {
......
......@@ -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)
{
......
......@@ -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
in the project directory for a given file path:
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.
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
{
......
......@@ -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) :
......
......@@ -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)
{
......
......@@ -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
* \return whether or not it was necessary to "enter" a schema for the supplied union index
* Returns whether or not it was necessary to enter a schema for the
* supplied union index.
*/
bool JsonSchema::maybeEnterNestedUnionSchema(int index)
{
......@@ -673,16 +677,13 @@ JsonSchemaManager::~JsonSchemaManager()
}
/*!
* \brief JsonManager::schemaForFile
*
* Try to find a JSON schema to which the supplied file can be validated against. According
* Tries to find a JSON schema to validate \a fileName 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
* \return a valid schema or 0
* Returns a valid schema or 0.
*/
JsonSchema *JsonSchemaManager::schemaForFile(const QString &fileName) const
{
......
......@@ -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.
......
......@@ -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 =
......
......@@ -42,13 +42,13 @@
Looks similar to FileWizardPage, but provides additional
functionality:
\list
\li Description label at the top for displaying introductory text
\li It does on the fly validation (connected to changed()) and displays
warnings/errors in a status label at the bottom (the page is complete
\li Contains a description label at the top for displaying introductory text.
\li Does on the fly validation (connected to changed()) and displays
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.
......
......@@ -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 The backslash quotes the following character
\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,
......@@ -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 A string enclosed in double quotes is not split
\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:
\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,
......
......@@ -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.
*/
......
......@@ -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
......
......@@ -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)
the services list might not be synchronized with respect to this signal
This signal is called when a service is added (convenience method).
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)
the services list might not be synchronized with respect to this signal
This signal is called when a service is removed (convenience method).
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
services(), use this signal, not serviceChanged(), serviceAdded() or serviceRemoved() to know
It might collect several serviceChanged signals together. If you use the list
returned by services(), use this signal, not serviceChanged(), serviceAdded(),
or serviceRemoved() to learn
about changes to the list.
*/
/*!
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment