To generate the documentation, QDoc goes through the source code and generates documentation for C++ types such as classes. QDoc then associates member functions, properties, and other types to the appropriate class.
Note that the documentation must be in the implementation files such as
.cpp
.
Class documentation is generated using the \class command and the name of the class as the first argument.
/*!
\class QCache
\brief The QCache class is a template class that provides a cache.
\ingroup tools
\ingroup shared
\reentrant
QCache\<Key, T\> defines a cache that stores objects of type T
associated with keys of type Key. For example, here's the
definition of a cache that stores objects of type Employee
associated with an integer key:
\snippet code/doc_src_qcache.cpp 0
这里是如何将对象插入缓存：
\snippet code/doc_src_qcache.cpp 1
... detailed description omitted
\sa QPixmapCache, QHash, QMap
*/
Context commands add information about the class, such as its module or which version the class was added.
Some common context commands are:
brief description is marked with the \brief command and it is for summarizing the purpose or functionality of the class. For C++ classes, QDoc will take the class and create annotated information for the class. The annotated information appears in lists and tables which display the class.
The C++ brief should start with:
"The <C++ class name> class"
detailed description section starts after the brief description. It provides more information about the class. The detailed description may contain images, snippet code, or links to other relevant documents. There must be an empty line which separates the brief and detailed description.
Typically, function documentation immediately precedes the implementation of the function in the
.cpp
file. For function documentation that is not immediately above the implementation, the
\fn
is needed.
/*! \fn QString &QString::remove(int position, int n) Removes \a n characters from the string, starting at the given \a position index, and returns a reference to the string. If the specified \a position index is within the string, but \a position + \a n is beyond the end of the string, the string is truncated at the specified \a position. \snippet qstring/main.cpp 37 \sa insert(), replace() */ QString &QString::remove(int pos, int len)
The function documentation starts with a verb, indicating the operation the function performs. This also applies to constructors and destructors.
Some common verbs for function documentation:
The function documentation must document:
\a command marks the parameter in the documentation. The return type documentation should link to the type documentation or be marked with the \c command in the case of boolean values.
/*!
Returns \c true if a QScroller object was already created for \a target; \c false otherwise.
\sa scroller()
*/
bool QScroller::hasScroller(QObject *target)
The property documentation resides immediately above the read function's implementation. The topic command for properties is \property .
/*!
\property QVariantAnimation::duration
\brief the duration of the animation
This property describes the duration in milliseconds of the
animation. The default duration is 250 milliseconds.
\sa QAbstractAnimation::duration()
*/
int QVariantAnimation::duration() const
Property documentation usually starts with "This property...", but these are alternate expressions:
true
when... and
false
when..." - for properties that are read.
Property documentation must include:
类似于
functions
, the default type may be linked or marked with the
\c
命令。
An example of a value range style is:
The values range from 0.0 (no blur) to maximumRadius (maximum blur). By default, the property is set to 0.0 (no blur).
topic command for signals, notifiers, and slots is \fn . Signal documentation state when they are triggered or emitted.
/*! \fn QAbstractTransition::triggered() This signal is emitted when the transition has been triggered (after onTransition() has been called). */
Signal documentation typically begin with "This signal is triggered when...". Here are alternate styles:
For slots or notifiers, the condition when they are executed or triggered by a signal should be documented.
For properties that have overloaded signals, QDoc groups the overloaded notifiers together. To refer to a specific version of a notifier or signal, simply refer to the property and mention that there are different versions of the notifier.
/*!
\property QSpinBox::value
\brief the value of the spin box
setValue() will emit valueChanged() if the new value is different
from the old one. The \l{QSpinBox::}{value} property has a second notifier
signal which includes the spin box's prefix and suffix.
*/
Enums, namespaces, and macros have a topic command for their documentation:
The language style for these types mention that they are an enum or a macro and continues with the type description.
For enumerations, the \value command is for listing the values. QDoc creates a table of values for the enum.
/*!
\enum QSql::TableType
This enum type describes types of SQL tables.
\value Tables All the tables visible to the user.
\value SystemTables Internal tables used by the database.
\value Views All the views visible to the user.
\value AllTables All of the above.
*/