QDoc Style Guidelines: Difference between revisions
m (Fixed typo) |
mNo edit summary |
||
(One intermediate revision by the same user not shown) | |||
Line 1: | Line 1: | ||
[[Category:Writing Guidelines]] | [[Category:Writing Guidelines]] | ||
This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]]. Though there are exceptions, following the guidelines ensures consistency across modules and Qt tools. | This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]]. Though there are exceptions, following the guidelines ensures consistency across modules and Qt tools. | ||
Line 8: | Line 7: | ||
Here are some basic guidelines for using QDoc commands: | Here are some basic guidelines for using QDoc commands: | ||
* | * When providing a link, use the title of the page, class, or QML type with the command. Don't use the HTML file name. | ||
*The space between the command and the left curly bracket is not needed and adds extra whitespace. For example: | * The space between the command and the left curly bracket is not needed and adds extra whitespace. For example: | ||
\l{Page Title} vs. \l {Page Title} | \l{Page Title} vs. \l {Page Title} | ||
*It is best to have the contents within {} on one line as this helps to spot errors and is easier to search. | * It is best to have the contents within {} on one line as this helps to spot errors and is easier to search. | ||
*Documentation comments within .cpp or code files should follow the consistency and column width set by the surrounding code. It is set to 80 columns for Qt code (though exceptions exist). | * Documentation comments within .cpp or code files should follow the consistency and column width set by the surrounding code. It is set to 80 columns for Qt code (though exceptions exist). | ||
==Markup and Code Blocks== | ==Markup and Code Blocks== | ||
Line 20: | Line 19: | ||
Marked up text notifies the reader that the text is special, either they are code or special keywords. | Marked up text notifies the reader that the text is special, either they are code or special keywords. | ||
* | * '''\b{bold}'''. Use bold to highlight special words. Limit the use of bold as it can attract too much attention. | ||
* | * '''\e{emphasis}'''. Emphasized words are typically rendered in italics, therefore, follow the regular American rules for emphasis or italicization. For example, use this command for special keywords followed by its definition. | ||
* | * '''\code ... \endcode'''. See paragraph below about the use of code blocks. | ||
These QDoc commands are for writing code to be typed by the developer: | These QDoc commands are for writing code to be typed by the developer: | ||
<!-- These blocks are broken, no qdoc commands represented here --> | <!-- These blocks are broken, no qdoc commands represented here --> | ||
- the parameter for the command is displayed as monospace font, indicating it is code, return value, or a value used directly by the developer. | * '''\c''' - the parameter for the command is displayed as monospace font, indicating it is code, return value, or a value used directly by the developer. | ||
and''' - content within the two commands are for writing code samples and is displayed in monospace font bound by a box. Syntax highlighting is enabled.''' | * '''\code''' and '''\endcode''' - content within the two commands are for writing code samples and is displayed in monospace font bound by a box. '''Syntax highlighting is enabled.''' | ||
* '''\qml''' and '''\endqml''' - for valid (and parseable) QML code. QDoc may give warnings if the code is not parseable. '''Syntax highlighting is enabled.''' | |||
*''' and''' - for valid (and parseable) QML code. QDoc may give warnings if the code is not parseable. Syntax highlighting is enabled. | * '''\badcode''' and '''\endcode''' - Use this for command-line code or code outside of Qt (neither C++, JavaScript, nor QML). QDoc does not try to parse and highlight the code. '''Syntax highlighting disabled.''' | ||
*''' and''' - | |||
These commands render their arguments in a specific way. | These commands render their arguments in a specific way. | ||
*''' - See Also and creates a link to pages. Use to refer readers to similar topics.''' | * '''\sa''' - See Also and creates a link to pages. Use to refer readers to similar topics. | ||
* '''\note''' - QDoc renders the parameter in a box. Use this command to refer to special information. | |||
- | * '''\warning''' - Similar to \note, but use this command for information that can cause errors or warnings. | ||
- | |||
==UI Texts== | ==UI Texts== | ||
Use \uicontrol to display UI texts. UI texts are displayed to the end-user, for example, File in the file menu for many desktop applications. They are commonly used to direct the reader to click or read a particular text within their application. QDoc renders the text in bold. | Use '''\uicontrol''' to display UI texts. UI texts are displayed to the end-user, for example, File in the file menu for many desktop applications. They are commonly used to direct the reader to click or read a particular text within their application. QDoc renders the text in bold. | ||
\gui is also a valid command for UI text. However, it is deprecated and \uicontrol is recommended because its name and usage are closer to other documentation tools. | '''\gui''' is also a valid command for UI text. However, it is deprecated and '''\uicontrol''' is recommended because its name and usage are closer to other documentation tools. | ||
==Brief Description with== | ==Brief Description with== | ||
The brief description is displayed in the API pages and in annotated lists. | The brief description is displayed in the API pages and in annotated lists. | ||
* Due to compatibility reasons, the brief statement for C++ API should start with "The <CLASS> class…". | |||
* For QML API, the brief statement should start with "<VERB>…" | |||
*For QML API, the brief statement should start with "<VERB>…" | * For other pages, follow the style for QML brief descriptions. | ||
*For other pages, follow the style for QML brief descriptions. | * Always terminate the brief with a period '''.'''. | ||
*Always terminate the brief with a period '''.'''. | |||
For more information, visit [[CppDocumentationStyle | C++ Documentation Style]] and [[QMLDocumentationStyle | QML Documentation Style]]. | For more information, visit [[CppDocumentationStyle | C++ Documentation Style]] and [[QMLDocumentationStyle | QML Documentation Style]]. | ||
Line 62: | Line 58: | ||
==Table of Contents and Page Navigation== | ==Table of Contents and Page Navigation== | ||
*''' and''' are for creating navigation links for a page. They should be written after the command but before the command. | * '''\nextpage''' and '''\previouspage''' are for creating navigation links for a page. They should be written after the '''\title''' command but before the '''\brief''' command. | ||
*Qt documentation hosted online and in Qt Creator is set up to utilize only '''\section1''', '''\section2''', and '''\section3''' as pages' CSS only support three section levels. | * Qt documentation hosted online and in Qt Creator is set up to utilize only '''\section1''', '''\section2''', and '''\section3''' as pages' CSS only support three section levels. | ||
*Projects not displayed within the Qt website may set the '''HTML.tocdepth''' variable in their respective QDoc HTML templates. For Qt 5, it is set to '''HTML.tocdepth = 2'''. | * Projects not displayed within the Qt website may set the '''HTML.tocdepth''' variable in their respective QDoc HTML templates. For Qt 5, it is set to '''HTML.tocdepth = 2'''. |
Latest revision as of 13:23, 10 June 2024
This page is part of the Qt Writing Guidelines. Though there are exceptions, following the guidelines ensures consistency across modules and Qt tools.
QDoc Commands and Whitespace
Here are some basic guidelines for using QDoc commands:
- When providing a link, use the title of the page, class, or QML type with the command. Don't use the HTML file name.
- The space between the command and the left curly bracket is not needed and adds extra whitespace. For example:
\l{Page Title} vs. \l {Page Title}
- It is best to have the contents within {} on one line as this helps to spot errors and is easier to search.
- Documentation comments within .cpp or code files should follow the consistency and column width set by the surrounding code. It is set to 80 columns for Qt code (though exceptions exist).
Markup and Code Blocks
Marked up text notifies the reader that the text is special, either they are code or special keywords.
- \b{bold}. Use bold to highlight special words. Limit the use of bold as it can attract too much attention.
- \e{emphasis}. Emphasized words are typically rendered in italics, therefore, follow the regular American rules for emphasis or italicization. For example, use this command for special keywords followed by its definition.
- \code ... \endcode. See paragraph below about the use of code blocks.
These QDoc commands are for writing code to be typed by the developer:
- \c - the parameter for the command is displayed as monospace font, indicating it is code, return value, or a value used directly by the developer.
- \code and \endcode - content within the two commands are for writing code samples and is displayed in monospace font bound by a box. Syntax highlighting is enabled.
- \qml and \endqml - for valid (and parseable) QML code. QDoc may give warnings if the code is not parseable. Syntax highlighting is enabled.
- \badcode and \endcode - Use this for command-line code or code outside of Qt (neither C++, JavaScript, nor QML). QDoc does not try to parse and highlight the code. Syntax highlighting disabled.
These commands render their arguments in a specific way.
- \sa - See Also and creates a link to pages. Use to refer readers to similar topics.
- \note - QDoc renders the parameter in a box. Use this command to refer to special information.
- \warning - Similar to \note, but use this command for information that can cause errors or warnings.
UI Texts
Use \uicontrol to display UI texts. UI texts are displayed to the end-user, for example, File in the file menu for many desktop applications. They are commonly used to direct the reader to click or read a particular text within their application. QDoc renders the text in bold.
\gui is also a valid command for UI text. However, it is deprecated and \uicontrol is recommended because its name and usage are closer to other documentation tools.
Brief Description with
The brief description is displayed in the API pages and in annotated lists.
- Due to compatibility reasons, the brief statement for C++ API should start with "The <CLASS> class…".
- For QML API, the brief statement should start with "<VERB>…"
- For other pages, follow the style for QML brief descriptions.
- Always terminate the brief with a period ..
For more information, visit C++ Documentation Style and QML Documentation Style.
Linking to other Pages or Sections
The topic of linking is covered in a separate page: QDoc Linking Guidelines
- \nextpage and \previouspage are for creating navigation links for a page. They should be written after the \title command but before the \brief command.
- Qt documentation hosted online and in Qt Creator is set up to utilize only \section1, \section2, and \section3 as pages' CSS only support three section levels.
- Projects not displayed within the Qt website may set the HTML.tocdepth variable in their respective QDoc HTML templates. For Qt 5, it is set to HTML.tocdepth = 2.