These commands are for indicating that a documented element has some special status. The element could be marked 弃用 , that is, it's about to be made obsolete and no longer included in the public interface. The \since command is for specifying the version number in which a function or class first appeared. The \qmlabstract command is for marking a QML type as an abstract base class.
\abstract is a synonym for the \qmlabstract command. Add this command to the \qmltype comment for a QML type when that type is meant to be used only as an abstract base type. When a QML type is abstract, it means that the QML type that can't be instantiated. Instead, the properties in its public API are included in the public properties list on the reference page for each QML type that inherits the abstract QML type. The properties are documented as if they are properties of the inheriting QML type.
Normally, when a QML type is marked with \qmlabstract , it is also marked with \internal so that its reference page is not generated. It the abstract QML type is not marked internal, it will have a reference page in the documentation.
The \default command is used for documenting a default value for a QML property. The command takes a single argument, which is displayed in the documentation as the default value.
/*!
\qmlproperty real Item::x
\default 0.0
*/
If the default value is a non-empty string, use quotes:
/*!
\qmlproperty string Item::state
\default "invalid"
*/
The \qmldefault command is for marking a QML property as the
default property
. The word
default
is displayed in the documentation of the property.
/*!
\qmlproperty list<Change> State::changes
This property holds the changes to apply for this state.
\qmldefault
By default, these changes are applied against the default state. If the state
extends another state, then the changes are applied against the state being
extended.
*/
See how QDoc renders this property on the reference page for the State 类型。
The \dontdocument command is only used in a dontdocument.qdoc file for a particular module. This file specifies publically declared classes or structs that are not meant to be documented. QDoc will not print warnings about missing \class comments for these classes and structs.
Below you will find the \dontdocument command in the dontdocument.qdoc for widgets:
/*! \dontdocument (QTypeInfo QMetaTypeId) */
The \inheaderfile meta-command is used for overriding the include statement generated for a C++ class, namespace, or header file reference documentation.
By default, QDoc documents a
\class SomeClass
to be available with a following include statement:
#include <SomeClass>
If the actual include statement differs from the default, this can be documented as
\class SomeClass \inheaderfile Tools/SomeClass ...
另请参阅 \class and \headerfile .
The \obsolete command is superceded by the \deprecated command.
This command is kept for backwards compatibility reasons only. It may be removed in a future version of QDoc. Use the \deprecated command instead.
另请参阅 \deprecated .
The \deprecated command is for indicating that a function is being deprecated, and that it should no longer be used in new code. There is no guarantee for how long it will remain in the library.
The \deprecated command takes two optional arguments:
When generating the reference documentation for a class, QDoc will create and link to a separate page documenting its deprecated functions. It is good practice to suggest an equivalent function as an alternative.
/*!
\fn MyClass::MyDeprecatedFunction
\deprecated [6.2] Use MyNewFunction() instead.
*/
QDoc renders this in
myclass-obsolete.html
as:
The following class members are deprecated. We strongly advise against using them in new code.
...
(弃用)
This function is deprecated since 6.2. It is provided to keep old source code working. We strongly advise against using it in new code. Use MyNewFunction() instead.
...
The \internal command indicates that the referenced function is not part of the public interface.
The command must stand on its own line.
QDoc ignores the documentation as well as the documented item, when generating the associated class reference documentation.
/*!
\internal
Tries to find the decimal separator. If it can't find
it and the thousand delimiter is != '.' it will try to
find a '.';
*/
int QDoubleSpinBoxPrivate::findDelimiter
(const QString &str, int index) const
{
int dotindex = str.indexOf(delimiter, index);
if (dotindex == -1 && thousand != dot && delimiter != dot)
dotindex = str.indexOf(dot, index);
return dotindex;
}
This function will not be included in the documentation, unless QDoc is called with the
-showinternal
command line option or the
QDOC_SHOW_INTERNAL
environment variable is set.
The \modulestate command can be used within a \module or \qmlmodule topic to provide a module state description other than preliminary or 弃用 .
Rest of the line is taken as an argument that describes the module's state. For example:
/*!
\module QtFoo
\modulestate Technical Preview
*/
QDoc will then add this information on the module page:
此模块在 技术预览 状态。
In HTML output, this state information appears also in the navigation bar (breadcrumbs) of reference pages for the module's members.
The \preliminary command is for indicating that a referenced function is still under development.
The command must stand on its own line.
The \preliminary command expands to a notification in the function documentation, and marks the function as preliminary when it appears in lists.
/*!
\preliminary
Returns information about the joining type attributes of the
character (needed for certain languages such as Arabic or
Syriac).
*/
QChar::JoiningType QChar::joiningType() const
{
return QChar::joiningType(ucs);
}
QDoc renders this as:
This function is under development and subject to change.
Returns information about the joining type attributes of the character (needed for certain languages such as Arabic or Syriac).
And the function's entry in QChar 's list of public functions will be rendered as:
(preliminary)
The \readonly command is used in conjunction with a \qmlproperty command to mark the QML property as read-only.
The \required command is used in conjunction with a \qmlproperty command to mark the QML property as required.
另请参阅 特性系统 .
The \since command tells in which minor release the associated functionality was added.
/*!
\since 4.1
Returns an icon for \a standardIcon.
...
\sa standardPixmap()
*/
QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const
{
}
QDoc renders this as:
This function was introduced in Qt version 4.1.
Returns an icon for standardIcon .
...
另请参阅 standardPixmap ().
If the argument passed to \since contains no spaces, it is assumed to be a version number string for the Qt project, and QDoc will prefix it with 'Qt' in the generated output. The argument can also contain the project name explicitly:
\since MyFramework 2.0
In this case, the arguments (project and version) are used as is.
Since QDoc version 6.5, C++ classes and QML types inherit the \since statement from their respective 模块 or QML 模块 , unless \since is explicitly used in the type documentation.
The \value command allows an optional since clause, enclosed in square brackets, to immediately follow the command string. This is used for marking specific C++ enum values with since information.
另请参阅 \value and ignoresince .
The \wrapper command, when used in a C++ class documentation, marks the class as a wrapper that provides access to a non-Qt API. This command is used for suppressing warnings that might otherwise be generated for members of such a class.
文档导航 线程支持