diff options
Diffstat (limited to 'src/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc')
-rw-r--r-- | src/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc | 187 |
1 files changed, 0 insertions, 187 deletions
diff --git a/src/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc b/src/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc deleted file mode 100644 index 9420c799b..000000000 --- a/src/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc +++ /dev/null @@ -1,187 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtwritingstyle-cpp.html -\title C++ Documentation Style -\brief Style guidelines for C++ documentation - -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 \c .cpp. - -\section1 Class Documentation - -Class documentation is generated using the \l{class-command}{\\class} command and -the name of the class as the first argument. - -\snippet examples/cpp.qdoc.sample class - -\l{Context commands} add information about the class, such as its module or -which version the class was added. - -Some common context commands are: -\list -\li \l{brief-command}{\\brief} - the class' brief description \b (mandatory) -\li \l{since-command}{\\since} - the version to which the class was added \b (mandatory) -\li \l{internal-command}{\\internal} - marks the class as internal. Internal -classes do not appear in the public API documentation. -\endlist - - -\section2 The Brief and Detailed Description - -The \e{brief description} is marked with the \l{brief-command}{\\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: -\code -"The <C++ class name> class" -\endcode - -The \e{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. - -\section1 Member Functions - -Typically, function documentation immediately precedes the implementation of the -function in the \c .cpp file. For function documentation that is not immediately -above the implementation, the \l{fn-command}{\\fn} is needed. - -\snippet examples/cpp.qdoc.sample function - -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: -\list -\li "Constructs..." - for constructors -\li "Destroys..." - for destructors -\li "Returns..." - for accessor functions -\endlist - -The function documentation must document: -\list -\li the return type -\li the parameters -\li the actions of the functions -\endlist - -The \l{a-command}{\\a} command marks the parameter in the documentation. -The return type documentation should link to the type documentation or be -marked with the \l{c-command}{\\c} command in the case of boolean values. - -\snippet examples/cpp.qdoc.sample return - -\section1 Properties - -The property documentation resides immediately above the read function's -implementation. The \l{writing-topic-commands}{topic command} for properties is -\l{property-command}{\\property}. - -\snippet examples/cpp.qdoc.sample property - -Property documentation usually starts with "This property...", but these are -alternate expressions: -\list -\li "This property holds..." -\li "This property describes..." -\li "This property represents..." -\li "Returns \c true when... and \c false when..." - for properties that -are read. -\li "Sets the..." - for properties that configure a type. -\endlist - -Property documentation must include: -\list -\li description and behavior of the property -\li accepted values for the property -\li the default value of the property -\endlist -Similar to \l{Member Functions}{functions}, the default type may be linked -or marked with the \c{\c} command. - -An example of a value range style is: -\quotation -The values range from 0.0 (no blur) to maximumRadius (maximum blur). By default, the property is set to 0.0 (no blur). -\endquotation - -\section1 Signals, Notifiers, and Slots -The \l{writing-topic-commands}{topic command} for signals, notifiers, and slots -is \l{fn-command}{\\fn}. Signal documentation state when they are triggered -or emitted. - -\snippet examples/cpp.qdoc.sample signals - -Signal documentation typically begin with "This signal is triggered when...". -Here are alternate styles: -\list -\li "This signal is triggered when..." -\li "Triggered when..." -\li "Emitted when..." -\endlist - -For slots or notifiers, the condition when they are executed or triggered by -a signal should be documented. -\list -\li "Executed when..." -\li "This slot is executed when..." -\endlist - -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. - -\snippet examples/cpp.qdoc.sample overloaded notifier - -\section1 Enums, Namespaces, and Other Types - -Enums, namespaces, and macros have a \l{writing-topic-commands}{topic command} for their documentation: -\list -\li \l{enum-command}{\\enum} -\li \l{typedef-command}{\\typedef} -\li \l{macro-command}{\\macro} -\endlist - -The language style for these types mention that they are an enum or a macro and -continues with the type description. - -For enumerations, the \l{value-command}{\\value} command is for listing the -values. QDoc creates a table of values for the enum. - -\snippet examples/cpp.qdoc.sample enums - -*/ - |