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.
...
(deprecated)
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 \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() .
QDoc generates the "Qt" reference from the
project
configuration variable. For that reason this reference will change according to the current documentation project.
另请参阅
project
.