QDoc Linking Guidelines: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
No edit summary
Line 1: Line 1:
=QDoc Linking Guidelines=
h1. QDoc Linking Guidelines


This page is part of the [[QtWritingGuidelines|Qt Writing Guidelines]]
This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]]


This page contains information about creating links to <span class="caps">API</span> pages and other articles and content.<br />'''Note:''' This applies to '''Qt 5''' QDoc only.
This page contains information about creating links to API pages and other articles and content.<br />'''Note:''' This applies to '''Qt 5''' QDoc only.


==Enabling Linking to Content Outside a Module==
== Enabling Linking to Content Outside a Module ==


To link to a section, <span class="caps">API</span>, or page outside of the documentation project (content not included in the .qdocconf file), the module name must be set to the '''depends''' qdocconf variable.<br />
To link to a section, API, or page outside of the documentation project (content not included in the .qdocconf file), the module name must be set to the '''depends''' qdocconf variable.<br /><code>depends ''= qtcore qtxmlpatterns qtqml qtgui qtlinguist <code>
 
<br />The depends entry corresponds to the directories found in the '''QT_INSTALL_DOCS''' directory.
The depends entry corresponds to the directories found in the '''QT_INSTALL_DOCS''' directory.
<br />'''Note''': To link to pages outside of the module, consider using the '''[]''' syntax as explained in the ''Resolving Ambiguous or Colliding Link Names'' section below.
 
<br />h2. Using QDoc's Autolink Feature
'''Note''': To link to pages outside of the module, consider using the '''[]''' syntax as explained in the ''Resolving Ambiguous or Colliding Link Names'' section below.
<br />QDoc detects certain keywords such as C''+ class names and attempts to link create links to them. Therefore, there is no need<br />to use the ''' command to create a link.
 
<br />h2. Using the Command
==Using QDoc’s Autolink Feature==
<br />In general, to create a link, use the''' command followed by the link name.<br /></code><br />{Link Name}<br /><code><br />Valid link names include:<br />* Page title<br />* Class name<br />* QML Type name<br />* Targets created by ''' and'''<br />* HTTP URLs<br />* Section titles with the '''PageTitle#SectionTitle''' syntax<br />* API members such as properties and functions with the '''APIPage::member''' syntax. For example '''Button::checked'''
 
QDoc detects certain keywords such as C++ class names and attempts to link create links to them. Therefore, there is no need<br /> to use the '''\l''' command to create a link.
 
==Using the \l Command==
 
In general, to create a link, use the '''\l''' command followed by the link name.<br /> Valid link names include:
 
* Page title
* Class name
* <span class="caps">QML</span> Type name
* Targets created by '''\keyword''' and '''\target'''
* <span class="caps">HTTP</span> <span class="caps">URL</span>s
* Section titles with the '''PageTitle#SectionTitle''' syntax
* <span class="caps">API</span> members such as properties and functions with the '''<span class="caps">APIP</span>age::member''' syntax. For example '''Button::checked'''


'''Notes:'''
'''Notes:'''


* The parentheses '''()''' after <span class="caps">QML</span> or C++ functions are required, while for <span class="caps">QML</span> properties they are not required.<br /> For example:<br />
* The parentheses '''''' after QML or C++ functions are required, while for QML properties they are not required.<br />For example:<br /></code><br />{Button::checked} - creates a link to the Button's checked property<br />{Button::clicked()} - creates a link to the Button's clicked() signal<br /><code>
* Typing '''\l{Button::}{clicked()}''' is a convenient shortcut for displaying a link to Button::clicked() as ''clicked()''.
* Typing '''{Button::}{clicked()}''' is a convenient shortcut for displaying a link to Button::clicked() as ''clicked()''.


* The space after the \l is not necessary if it is followed with '''{}''' as it adds unnecessary whitespace. Instead of \l {Page},<br /> type either '''\l{Page}''' or when there is only one word, '''\l Page'''.
* The space after the is not necessary if it is followed with '''{}''' as it adds unnecessary whitespace. Instead of {Page},<br />type either '''{Page}''' or when there is only one word, '''Page'''.


===Visible Text===
=== Visible Text ===


Sometimes, to integrate the link name into the sentence or clause, the visible text is necessary.
Sometimes, to integrate the link name into the sentence or clause, the visible text is necessary.


* The '''\l{Signals &amp; Slots#Advanced Signals and Slots Usage}{advanced signals and slots example}''' demonstrates a<br /> use for QSignalMapper.
* The '''{Signals &amp; Slots#Advanced Signals and Slots Usage}{advanced signals and slots example}''' demonstrates a<br />use for QSignalMapper.
 
==Resolving Ambiguous or Colliding Link Names==
 
To disambiguate links, QDoc allows the author to specify the QDoc project and the type of <span class="caps">API</span> using<br />'''[]''' after the link command.
 
For example:
 
* '''\l[QML]{EnginioClient}''' – creates a link to the EnginioClient <span class="caps">QML</span> type
* '''\l[CPP]{EnginioClient}''' – creates a link to the EnginioClient C++ class
* '''\l[QtCore]{Qt}''' – creates a link to the Qt namespace
* '''\l[QtQml]{Qt}''' – creates a link to the Qt <span class="caps">QML</span> type


Currently only these parameters within '''[]''' are recognized:
== Resolving Ambiguous or Colliding Link Names ==


* '''<span class="caps">QML</span>''' – for <span class="caps">QML</span> types, enumerations, or other definitions in <span class="caps">QML</span> modules (specified with \qmlmodule)
To disambiguate links, QDoc allows the author to specify the QDoc project and the type of API using<br />'''[]''' after the link command.
* '''<span class="caps">CPP</span>''' – for C++ <span class="caps">API</span>s
* project or module name


'''Note:''' The project name is specifed in the QDoc configuration file (*.qdocconf).
For example:<br />* '''[QML]{EnginioClient}''' - creates a link to the EnginioClient QML type<br />* '''[CPP]{EnginioClient}''' - creates a link to the EnginioClient C++ class<br />* '''[QtCore]{Qt}''' - creates a link to the Qt namespace<br />* '''[QtQml]{Qt}''' - creates a link to the Qt QML type


==External Pages==
Currently only these parameters within '''[]''' are recognized:<br />* '''QML''' - for QML types, enumerations, or other definitions in QML modules (specified with )<br />* '''CPP''' - for C++ APIs<br />* project or module name


To avoid multiple instances of ''hard-coded'' <span class="caps">HTTP</span> <span class="caps">URL</span>s, use the '''\externalpage''' command to associate the <span class="caps">HTTP</span> <span class="caps">URL</span><br /> with a title.<br />'''\l{An Example Page}''' creates link to http://www.example.com. There is a set of external page in ''qtbase/doc/global/externalsites''<br /> directory. The \externalpage command can be declared in the module documentation directory if it is not used anywhere else in Qt to avoid being<br /> unnecessarily included in other modules’ index files.
'''Note:''' The project name is specifed in the QDoc configuration file &amp;#40;'''.qdocconf&amp;amp;#41;.
<br />h2. External Pages
<br />To avoid multiple instances of ''hard-coded'' HTTP URLs, use the''' command to associate the HTTP URL<br />with a title.<br /></code><br />http://www.example.com<br />n Example Page<br /><code><br />'''{An Example Page}''' creates link to http://www.example.com. There is a set of external page in ''qtbase/doc/global/externalsites''<br />directory. The command can be declared in the module documentation directory if it is not used anywhere else in Qt to avoid being<br />unnecessarily included in other modules' index files.


==Various Guidelines==
== Various Guidelines ==


* It is best if the link title and visible text are in the same line so that they are more readable and easily searched.
* It is best if the link title and visible text are in the same line so that they are more readable and easily searched.
* Be mindful about colliding titles by avoiding certain keywords or by creating descriptive page titles.
* Be mindful about colliding titles by avoiding certain keywords or by creating descriptive page titles.
* Linking directly to the <span class="caps">HTML</span> filename should be used as a last resort because the filename can change.
* Linking directly to the HTML filename should be used as a last resort because the filename can change.
* QDoc searches for articles for links first and if there is a page with the same name in another module, use '''[]''' to specify the module name.

Revision as of 11:35, 24 February 2015

h1. QDoc Linking Guidelines

This page is part of the Qt Writing Guidelines

This page contains information about creating links to API pages and other articles and content.
Note: This applies to Qt 5 QDoc only.

Enabling Linking to Content Outside a Module

To link to a section, API, or page outside of the documentation project (content not included in the .qdocconf file), the module name must be set to the depends qdocconf variable.

depends ''= qtcore qtxmlpatterns qtqml qtgui qtlinguist <code>
<br />The depends entry corresponds to the directories found in the '''QT_INSTALL_DOCS''' directory.
<br />'''Note''': To link to pages outside of the module, consider using the '''[]''' syntax as explained in the ''Resolving Ambiguous or Colliding Link Names'' section below.
<br />h2. Using QDoc's Autolink Feature
<br />QDoc detects certain keywords such as C''+ class names and attempts to link create links to them. Therefore, there is no need<br />to use the ''' command to create a link.
<br />h2. Using the Command
<br />In general, to create a link, use the''' command followed by the link name.<br />


{Link Name}

<br />Valid link names include:<br />* Page title<br />* Class name<br />* QML Type name<br />* Targets created by ''' and'''<br />* HTTP URLs<br />* Section titles with the '''PageTitle#SectionTitle''' syntax<br />* API members such as properties and functions with the '''APIPage::member''' syntax. For example '''Button::checked'''

'''Notes:'''

* The parentheses '''''' after QML or C++ functions are required, while for QML properties they are not required.<br />For example:<br />


{Button::checked} - creates a link to the Button's checked property
{Button::clicked()} - creates a link to the Button's clicked() signal

* Typing '''{Button::}{clicked()}''' is a convenient shortcut for displaying a link to Button::clicked() as ''clicked()''.

* The space after the is not necessary if it is followed with '''{}''' as it adds unnecessary whitespace. Instead of {Page},<br />type either '''{Page}''' or when there is only one word, '''Page'''.

=== Visible Text ===

Sometimes, to integrate the link name into the sentence or clause, the visible text is necessary.

* The '''{Signals &amp; Slots#Advanced Signals and Slots Usage}{advanced signals and slots example}''' demonstrates a<br />use for QSignalMapper.

== Resolving Ambiguous or Colliding Link Names ==

To disambiguate links, QDoc allows the author to specify the QDoc project and the type of API using<br />'''[]''' after the link command.

For example:<br />* '''[QML]{EnginioClient}''' - creates a link to the EnginioClient QML type<br />* '''[CPP]{EnginioClient}''' - creates a link to the EnginioClient C++ class<br />* '''[QtCore]{Qt}''' - creates a link to the Qt namespace<br />* '''[QtQml]{Qt}''' - creates a link to the Qt QML type

Currently only these parameters within '''[]''' are recognized:<br />* '''QML''' - for QML types, enumerations, or other definitions in QML modules (specified with )<br />* '''CPP''' - for C++ APIs<br />* project or module name

'''Note:''' The project name is specifed in the QDoc configuration file &amp;#40;'''.qdocconf&amp;amp;#41;.
<br />h2. External Pages
<br />To avoid multiple instances of ''hard-coded'' HTTP URLs, use the''' command to associate the HTTP URL<br />with a title.<br />


http://www.example.com
n Example Page

{An Example Page} creates link to http://www.example.com. There is a set of external page in qtbase/doc/global/externalsites
directory. The command can be declared in the module documentation directory if it is not used anywhere else in Qt to avoid being
unnecessarily included in other modules' index files.

Various Guidelines

  • It is best if the link title and visible text are in the same line so that they are more readable and easily searched.
  • Be mindful about colliding titles by avoiding certain keywords or by creating descriptive page titles.
  • Linking directly to the HTML filename should be used as a last resort because the filename can change.