Commit 0479abdc authored by Tobias Hunger's avatar Tobias Hunger
Browse files

QDoc: Fix QDoc warnings



This patch fixes ~1100 warnings from qdoc

Change-Id: Ia9555db675acbf8083b2f87d9855a62a3a34ccb9
Reviewed-by: default avatarLeena Miettinen <riitta-leena.miettinen@digia.com>
parent 529cc963
......@@ -35,10 +35,10 @@
Qt, such as:
\list
\o Widgets and layout managers
\o Container classes
\o Signals and slots
\o Input and output devices
\li Widgets and layout managers
\li Container classes
\li Signals and slots
\li Input and output devices
\endlist
All these technologies will be introduced via the Qt Creator Integrated
......@@ -53,13 +53,13 @@
Tutorial chapters:
\list 1
\o \l{examples/addressbook-sdk/part1}{Designing the User Interface}
\o \l{examples/addressbook-sdk/part2}{Adding Addresses}
\o \l{examples/addressbook-sdk/part3}{Navigating between Entries}
\o \l{examples/addressbook-sdk/part4}{Editing and Removing Addresses}
\o \l{examples/addressbook-sdk/part5}{Adding a Find Function}
\o \l{examples/addressbook-sdk/part6}{Loading and Saving}
\o \l{examples/addressbook-sdk/part7}{Additional Features}
\li \l{examples/addressbook-sdk/part1}{Designing the User Interface}
\li \l{examples/addressbook-sdk/part2}{Adding Addresses}
\li \l{examples/addressbook-sdk/part3}{Navigating between Entries}
\li \l{examples/addressbook-sdk/part4}{Editing and Removing Addresses}
\li \l{examples/addressbook-sdk/part5}{Adding a Find Function}
\li \l{examples/addressbook-sdk/part6}{Loading and Saving}
\li \l{examples/addressbook-sdk/part7}{Additional Features}
\endlist
Although this little application does not look much like a fully-fledged
......@@ -93,7 +93,7 @@
Begin by launching Qt Creator and use it to generate a new project. To
do this, select \gui{File} > \gui{New File or Project...} >
\gui{Qt Application Project} > \gui{Qt Gui Application} and
click \gui OK. Set your project name to \bold part1 with the QtCore and
click \gui OK. Set your project name to \b part1 with the QtCore and
QtGui modules checked. Ensure that you select QWidget as your base class
and name it \c AddressBook.
......@@ -101,15 +101,15 @@
\gui{Project}:
\list
\o \c{main.cpp} - the file containing a \c main() function, with an
instance of \c AddressBook,
\o \c{addressbook.cpp} - the implementation file for the
\c AddressBook class,
\o \c{addressbook.h} - the definition file for the \c AddressBook
class,
\o \c{addressbook.ui} - the user interface file created with \QD,
and
\o \c{part1.pro} - the project file.
\li \c{main.cpp} - the file containing a \c main() function, with an
instance of \c AddressBook,
\li \c{addressbook.cpp} - the implementation file for the
\c AddressBook class,
\li \c{addressbook.h} - the definition file for the \c AddressBook
class,
\li \c{addressbook.ui} - the user interface file created with \QD,
and
\li \c{part1.pro} - the project file.
\endlist
Now that you have all the files you need, click \gui Finish so you can
......@@ -132,16 +132,16 @@
QLineEdit and a QTextEdit for the input fields. To create this follow the
steps mentioned below:
\list
\o Drag those widgets from the \gui{Widget Box} to your form.
\o In the \gui{Property Editor}, set their \gui{objectName} property to
\c nameLabel and \c addressLabel for the \l{QLabel}s, \c nameLine
for the QLineEdit and finally, \c addressText for the QTextEdit.
\o Position the widgets properly, according to the screenshot above.
\o Use a QGridLayout to position our labels and input fields in a
structured manner. QGridLayout divides the available space into
a grid and places widgets in the cells you specify with row and
column numbers.
\o Place the caption of the \c addressLabel on the top, change the
\li Drag those widgets from the \gui{Widget Box} to your form.
\li In the \gui{Property Editor}, set their \gui{objectName} property to
\c nameLabel and \c addressLabel for the \l{QLabel}s, \c nameLine
for the QLineEdit and finally, \c addressText for the QTextEdit.
\li Position the widgets properly, according to the screenshot above.
\li Use a QGridLayout to position our labels and input fields in a
structured manner. QGridLayout divides the available space into
a grid and places widgets in the cells you specify with row and
column numbers.
\li Place the caption of the \c addressLabel on the top, change the
vertical alignment property to \c AlignTop.
\endlist
......@@ -227,15 +227,15 @@
the behavior of a widget has the following advantages:
\list
\o You can write implementations of virtual or pure virtual functions
to obtain exactly what you need, falling back on the base class's
implementation when necessary.
\o It allows you to encapsulate parts of the user interface within a
class, so that the other parts of the application do not need to
know about the individual widgets in the user interface.
\o The subclass can be used to create multiple custom widgets in the
same application or library, and the code for the subclass can be
reused in other projects.
\li You can write implementations of virtual or pure virtual functions
to obtain exactly what you need, falling back on the base class's
implementation when necessary.
\li It allows you to encapsulate parts of the user interface within a
class, so that the other parts of the application do not need to
know about the individual widgets in the user interface.
\li The subclass can be used to create multiple custom widgets in the
same application or library, and the code for the subclass can be
reused in other projects.
\endlist
Since Qt does not provided a specific address book widget, you subclass a
......@@ -272,29 +272,29 @@
complete the process of adding a contact. Break the existing layouts by
following the steps below:
\list
\o Select, \gui{Break Layout} from the context menu. You might have to
do a \gui{Select All} with \key{Ctrl+A} first..
\o Add three push buttons and double-click on each of them to set
their text to "Add", "Submit", and "Cancel".
\o Set the \c objectName of the buttons to \c addButton,
\c submitButton and \c cancelButton respectively.
\o A \gui{Vertical Spacer} is required to ensure that the push buttons
will be laid out neatly; drag one from the \gui{Widget Box}.
\o Lay out these three push buttons and the spacer vertically, by
selecting all three of them using \key{Ctrl + click} and selecting
\gui{Lay out Vertically} from the context menu. Alternatively you
can use the \key{Ctrl+L} shortcut key.
\note Use the spacer as you do not want the buttons to be evenly
spaced, but arranged closer to the top of the widget.
\o The figure below shows the difference between using the spacer and
not using it.
\image addressbook-tutorial-part2-stretch-effects.png
\o Select all the objects on the form using, \key{Ctrl+A} and lay them
out in a grid.
\o Lastly, set the top level widget's layout by right-clicking anywhere
on the widget and selecting \gui{Lay out Horizontally} or
\gui{Lay out Vertically}.
\li Select, \gui{Break Layout} from the context menu. You might have to
do a \gui{Select All} with \key{Ctrl+A} first..
\li Add three push buttons and double-click on each of them to set
their text to "Add", "Submit", and "Cancel".
\li Set the \c objectName of the buttons to \c addButton,
\c submitButton and \c cancelButton respectively.
\li A \gui{Vertical Spacer} is required to ensure that the push buttons
will be laid out neatly; drag one from the \gui{Widget Box}.
\li Lay out these three push buttons and the spacer vertically, by
selecting all three of them using \key{Ctrl + click} and selecting
\gui{Lay out Vertically} from the context menu. Alternatively you
can use the \key{Ctrl+L} shortcut key.
\note Use the spacer as you do not want the buttons to be evenly
spaced, but arranged closer to the top of the widget.
\li The figure below shows the difference between using the spacer and
not using it.
\image addressbook-tutorial-part2-stretch-effects.png
\li Select all the objects on the form using, \key{Ctrl+A} and lay them
out in a grid.
\li Lastly, set the top level widget's layout by right-clicking anywhere
on the widget and selecting \gui{Lay out Horizontally} or
\gui{Lay out Vertically}.
\endlist
The final design of the form is shown in the screenshot below:
......@@ -376,27 +376,27 @@
This function can be divided into three parts:
\list 1
\o Extract the contact's detail from \c nameLine and \c addressText
and store them in QString objects. Also validate to ensure that
you did not click \gui Submit with empty input fields;
otherwise, a QMessageBox is displayed to remind you for a name
and address.
\li Extract the contact's detail from \c nameLine and \c addressText
and store them in QString objects. Also validate to ensure that
you did not click \gui Submit with empty input fields;
otherwise, a QMessageBox is displayed to remind you for a name
and address.
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part1
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part1
\o Then proceed to check if the contact already exists. If it does
not exist, add the contact to \c contacts and display a
QMessageBox to inform you about this, preventing you from
adding duplicate contacts. Our \c contacts object is based on
key-value pairs or name and address, hence, you want to ensure that
\e key is unique.
\li Then proceed to check if the contact already exists. If it does
not exist, add the contact to \c contacts and display a
QMessageBox to inform you about this, preventing you from
adding duplicate contacts. Our \c contacts object is based on
key-value pairs or name and address, hence, you want to ensure that
\e key is unique.
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part2
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part2
\o Once you have handled both cases mentioned above, restore the
push buttons to their normal state with the following code:
\li Once you have handled both cases mentioned above, restore the
push buttons to their normal state with the following code:
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part3
\snippet examples/addressbook-sdk/part2/addressbook.cpp submitContact part3
\endlist
The screenshot below shows the QMessageBox object used to display
......@@ -457,17 +457,17 @@
need to traverse the existing contacts. To do so follow the steps
mentioned below:
\list
\o Add two push buttons at the bottom of your application and name
them: \gui Next and \gui Previous.
\o The buttons' \c objectName should be \c nextButton and
\c previousButton, respectively.
\o Break your top level layout by right-clicking on \c AddressBook in
the \gui{Object Inspector} and then select \gui{Lay out|Break Layout}.
\o Place the \gui Next and \gui Previous buttons in a horizontal
layout.
\o Drag and drop the buttons together with their layout into the
existing grid layout.
\o Set a top level layout for the widget again.
\li Add two push buttons at the bottom of your application and name
them: \gui Next and \gui Previous.
\li The buttons' \c objectName should be \c nextButton and
\c previousButton, respectively.
\li Break your top level layout by right-clicking on \c AddressBook in
the \gui{Object Inspector} and then select \gui{Lay out|Break Layout}.
\li Place the \gui Next and \gui Previous buttons in a horizontal
layout.
\li Drag and drop the buttons together with their layout into the
existing grid layout.
\li Set a top level layout for the widget again.
\endlist
The screenshot below illustrates what you will see as the button layout
......@@ -523,11 +523,11 @@
for \c contacts and then:
\list
\o If the iterator is not at the end of \c contacts, increment it by
\li If the iterator is not at the end of \c contacts, increment it by
one.
\o If the iterator is at the end of \c contacts, move it to the
beginning of \c contacts. This gives an illusion that our QMap
is working like a circularly-linked list.
\li If the iterator is at the end of \c contacts, move it to the
beginning of \c contacts. This gives an illusion that our QMap
is working like a circularly-linked list.
\endlist
\snippet examples/addressbook-sdk/part3/addressbook.cpp next
......@@ -539,11 +539,11 @@
\c contacts and then:
\list
\o If the iterator is at the end of \c contacts, clear the display
and return.
\o If the iterator is at the beginning of \c contacts, move it to
the end.
\o Then decrement the iterator by one.
\li If the iterator is at the end of \c contacts, clear the display
and return.
\li If the iterator is at the beginning of \c contacts, move it to
the end.
\li Then decrement the iterator by one.
\endlist
\snippet examples/addressbook-sdk/part3/addressbook.cpp previous
......@@ -578,9 +578,9 @@
In this chapter, define the \c Mode enum with three different values:
\list
\o \c{NavigationMode}
\o \c{AddingMode}
\o \c{EditingMode}
\li \c{NavigationMode}
\li \c{AddingMode}
\li \c{EditingMode}
\endlist
\section1 Placing Widgets on The Form
......
This diff is collapsed.
......@@ -44,22 +44,22 @@
\section1 Basics
\list
\o \l{Getting and Building Qt Creator}
\o \l{Creating Your First Plugin}
\o \l{Plugin Specifications}
\o \l{Plugin Life Cycle}
\li \l{Getting and Building Qt Creator}
\li \l{Creating Your First Plugin}
\li \l{Plugin Specifications}
\li \l{Plugin Life Cycle}
\endlist
\section1 Design Principles
\list
\o \l{The Plugin Manager, the Object Pool, and Registered Objects}
\o \l{Aggregations}
\o \l{Extending and Providing Interfaces}
\li \l{The Plugin Manager, the Object Pool, and Registered Objects}
\li \l{Aggregations}
\li \l{Extending and Providing Interfaces}
\endlist
\section1 Creating 3rd-Party Plugins
\list
\o \l{A Note on Binary Compatibility}
\o \l{Creating User-Installable Plugins}
\li \l{A Note on Binary Compatibility}
\li \l{Creating User-Installable Plugins}
\endlist
*/
......@@ -49,20 +49,20 @@
\table
\header
\o Tag
\o Meaning
\li Tag
\li Meaning
\row
\o externaltool
\o Root element in the XML file that specifies an external tool.
\li externaltool
\li Root element in the XML file that specifies an external tool.
\endtable
\table
\header
\o Attribute
\o Meaning
\li Attribute
\li Meaning
\row
\o id
\o A string that identifies the external tool.
Two tools cannot have the same id. Required.
\li id
\li A string that identifies the external tool.
Two tools cannot have the same id. Required.
\endtable
\section2 Description Tags
......@@ -74,30 +74,30 @@
\table
\header
\o Tag
\o Meaning
\li Tag
\li Meaning
\row
\o description
\o Short, one-line description of what the tool is for. Required.
\li description
\li Short, one-line description of what the tool is for. Required.
\row
\o displayname
\o Name to show in the menu item for the tool. Required.
\li displayname
\li Name to show in the menu item for the tool. Required.
\row
\o category
\o Name of the category to show the tool in.
This is the name of the sub menu of the \c { Tools > External }
menu where the tool is placed. For example, specify the value
\c "Text" to display the tool in the \c { Tools > External > Text }
menu. Required.
\li category
\li Name of the category to show the tool in.
This is the name of the sub menu of the \c { Tools > External }
menu where the tool is placed. For example, specify the value
\c "Text" to display the tool in the \c { Tools > External > Text }
menu. Required.
\endtable
\table
\header
\o Attribute
\o Meaning
\li Attribute
\li Meaning
\row
\o xml:lang
\o Language code (such as, \c "en" or \c "de") of the language that is used for
the description, display name, or category. Optional.
\li xml:lang
\li Language code (such as, \c "en" or \c "de") of the language that is used for
the description, display name, or category. Optional.
\endtable
\section2 Executable Specification Tag
......@@ -107,32 +107,32 @@
\table
\header
\o Tag
\o Meaning
\li Tag
\li Meaning
\row
\o executable
\o Encloses subtags that specify what to run and which parameters to use. Required.
\li executable
\li Encloses subtags that specify what to run and which parameters to use. Required.
\endtable
\table
\header
\o Attribute
\o Meaning
\li Attribute
\li Meaning
\row
\o output
\o Specifies how to handle the tool's standard output stream.
\li output
\li Specifies how to handle the tool's standard output stream.
Defaults to \c ShowInPane. Optional.
\row
\o error
\o Specifies how to handle the tool's standard error stream.
Defaults to \c ShowInPane. Optional.
\li error
\li Specifies how to handle the tool's standard error stream.
Defaults to \c ShowInPane. Optional.
\row
\o modifiesdocument
\o Specifies whether Qt Creator should expect changes to the current
document. If this flag is set, Qt Creator prompts users to save
changes to the current document before running the tool,
and silently reloads the current document after the tool has finished.
Possible values are: \c "yes" or \c "no" (defaults to \c "no").
Optional.
\li modifiesdocument
\li Specifies whether Qt Creator should expect changes to the current
document. If this flag is set, Qt Creator prompts users to save
changes to the current document before running the tool,
and silently reloads the current document after the tool has finished.
Possible values are: \c "yes" or \c "no" (defaults to \c "no").
Optional.
\endtable
The \c executable tag allows the following subtags. You must specify at least
......@@ -140,28 +140,28 @@
\table
\header
\o Subtag
\o Meaning
\li Subtag
\li Meaning
\row
\o path
\o File path to the executable to run, including filename. If you
specify the executable name without a path, Qt creator checks the
system PATH environment variable for a path to the executable. You
can specify the path multiple times. Qt Creator tries to resolve the
references in the given order and runs the first executable that it
finds. Required.
\li path
\li File path to the executable to run, including filename. If you
specify the executable name without a path, Qt creator checks the
system PATH environment variable for a path to the executable. You
can specify the path multiple times. Qt Creator tries to resolve the
references in the given order and runs the first executable that it
finds. Required.
\row
\o arguments
\o Command line arguments for the executable. Specify the string in the
same format (with respect to quoting and argument splitting, for
example) as you would specify it on the command line of the platform
the tool runs on. Optional.
\li arguments
\li Command line arguments for the executable. Specify the string in the
same format (with respect to quoting and argument splitting, for
example) as you would specify it on the command line of the platform
the tool runs on. Optional.
\row
\o workingdirectory
\o The working directory for the executable. Optional.
\li workingdirectory
\li The working directory for the executable. Optional.
\row
\o input
\o A potentially multiline string that is passed to the tool via standard input stream.
\li input
\li A potentially multiline string that is passed to the tool via standard input stream.
\endtable
\section1 Example
......
......@@ -36,81 +36,81 @@
your plugin with.
\list 1
\o Select \gui{File > New File or Project > Libraries > Qt Creator Plugin > Choose}.
\li Select \gui{File > New File or Project > Libraries > Qt Creator Plugin > Choose}.
\image firstplugin-wizard.png "Choose the \QC Plugin Wizard"
\image firstplugin-wizard.png "Choose the \QC Plugin Wizard"
The \gui{Introduction and Project Location} dialog opens.
The \gui{Introduction and Project Location} dialog opens.
\image firstplugin-nameandpath.png "Choose Name and Place of the Project"
\image firstplugin-nameandpath.png "Choose Name and Place of the Project"
\o Give your project a name and specify in which path
this project will be created. The actual plugin's name can be different
from the project name. You will choose that name later in the wizard.
Continue to the next page.
\li Give your project a name and specify in which path
this project will be created. The actual plugin's name can be different
from the project name. You will choose that name later in the wizard.
Continue to the next page.
The \gui{Kit Selection} dialog opens.
The \gui{Kit Selection} dialog opens.
\image firstplugin-kitselection.png "Choose the kit to build and run your project with"
\image firstplugin-kitselection.png "Choose the kit to build and run your project with"
\o Select the \l{glossary-buildandrun-kit}{kit} to build and run your project with.
For a \QC plugin this needs to be a kit with \gui{Desktop} device type,
and a Qt version that is compatible with the Qt version that your
\QC was built with (in the best case the exact same build).
If you use an incompatible Qt version to build your plugin, you
will get errors while \QC tries to load your plugin.
Continue to the next page.
\li Select the \l{glossary-buildandrun-kit}{kit} to build and run your project with.
For a \QC plugin this needs to be a kit with \gui{Desktop} device type,
and a Qt version that is compatible with the Qt version that your
\QC was built with (in the best case the exact same build).
If you use an incompatible Qt version to build your plugin, you
will get errors while \QC tries to load your plugin.
Continue to the next page.
The \gui{Plugin Information} dialog opens.
The \gui{Plugin Information} dialog opens.
\image firstplugin-pluginsetup.png "Specify Your Plugin Details"
\image firstplugin-pluginsetup.png "Specify Your Plugin Details"
\o In the \gui{Plugin name} field, type \gui{Example}. The name of the plugin
is used as its identifier, and also is the base for the file names and
classes in the code.
\li In the \gui{Plugin name} field, type \gui{Example}. The name of the plugin
is used as its identifier, and also is the base for the file names and
classes in the code.
\o The values of the following fields are mainly informational, and
are shown in the detailed view in \QC's plugin overview
(\gui{Help > About Plugins}, or \gui{Qt Creator > About Plugins}
on Mac).
\li The values of the following fields are mainly informational, and
are shown in the detailed view in \QC's plugin overview
(\gui{Help > About Plugins}, or \gui{Qt Creator > About Plugins}
on Mac).
\list
\o \gui{Vendor name} is a short one-word name of the company
or organization that created the plugin. This is also used for
the path name where the plugin will be deployed to.
\o \gui{Copyright} is a one-line, short copyright string.
\o \gui{License} is a multi-line license text (but shouldn't be pages over pages long,
since the interface doesn't allow nice reading of long texts).
\o \gui{Description} is a relatively short, but
possibly multi-line description of what the plugin does.
\o \gui{URL} is a website where the user can find more
information about the plugin and/or organization providing it.
\list
\li \gui{Vendor name} is a short one-word name of the company
or organization that created the plugin. This is also used for
the path name where the plugin will be deployed to.
\li \gui{Copyright} is a one-line, short copyright string.
\li \gui{License} is a multi-line license text (but shouldn't be pages over pages long,
since the interface doesn't allow nice reading of long texts).
\li \gui{Description} is a relatively short, but
possibly multi-line description of what the plugin does.
\li \gui{URL} is a website where the user can find more
information about the plugin and/or organization providing it.
\endlist
\o Set the \gui{Qt Creator sources} and \gui{Qt Creator build} fields to
the source and build directory of the \QC
instance you want to use to test your plugin with, respectively.
If you don't do that correctly you will get compile errors for your
plugin, and your plugin might not show up in \QC at all.
\o In the \gui{Deploy into} list, select \gui{Qt Creator build}. This sets
your .pro file up to deploy your plugin directly into your \QC build's
plugin directory (requires you to have write permissions there).
The other option, \gui{Local user settings}, sets your .pro file up to
deploy your plugin into \QC's user plugin path
(for example \c{~/.config/QtProject/qtcreator/plugins} on Unix systems).
We choose \gui{Qt Creator build} because we use a self-compiled
\QC, and want the plugin to be only loaded by that \QC
instance.
Continue to the next page.
The \gui{Project Management} dialog opens.
\image firstplugin-summary.png "Summary of Created Files"
\o Review the files that will be created, choose a version control
system that \QC should use for your project (always a good idea!),
and finish the wizard.
\li Set the \gui{Qt Creator sources} and \gui{Qt Creator build} fields to
the source and build directory of the \QC
instance you want to use to test your plugin with, respectively.
If you don't do that correctly you will get compile errors for your
plugin, and your plugin might not show up in \QC at all.
\li In the \gui{Deploy into} list, select \gui{Qt Creator build}. This sets
your .pro file up to deploy your plugin directly into your \QC build's
plugin directory (requires you to have write permissions there).
The other option, \gui{Local user settings}, sets your .pro file up to
deploy your plugin into \QC's user plugin path
(for example \c{~/.config/QtProject/qtcreator/plugins} on Unix systems).
We choose \gui{Qt Creator build} because we use a self-compiled
\QC, and want the plugin to be only loaded by that \QC
instance.
Continue to the next page.
The \gui{Project Management} dialog opens.
\image firstplugin-summary.png "Summary of Created Files"
\