summaryrefslogtreecommitdiffstats log msg author committer range
path: root/src/tools/qdoc/doc/qdoc-guide.qdoc
blob: e57c3857c57d7aefac970c9ee252d394a2559d55 (plain)
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690  /**************************************************************************** ** ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/ ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:FDL$ ** GNU Free Documentation License ** 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. ** ** Other Usage ** Alternatively, this file may be used in accordance with the terms ** and conditions contained in a signed written agreement between you ** and Nokia. ** ** ** ** ** ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \page qdoc-guide.html \title Getting Started with QDoc \nextpage Creating QDoc Configuration Files Qt uses QDoc to generate its documentation set into HTML and DITA XML formats. QDoc uses a set of configuration files to generate documentation from QDoc comments. The comments have types called \l{writing-topic-commands}{topics} that determine whether a comment is a class documentation or a property documentation. A comment may also have \l{writing-markup}{mark up} to enhance the layout and formatting of the final output. There are three essential materials for generating documentation with qdoc: \list \li \c QDoc binary \li \c qdocconf configuration files \li \c Documentation in \c C++, \c QML, and \c .qdoc files \endlist This section intends to cover the basic necessities for creating a documentation set. Additionally, the guide presents special considerations and options to documenting non-C++ API documentation as well as QML documentation. Finally, the guide will provide a sample project documentation and an example of a QML type documentation. For specific QDoc information, consult the \l{Table of Contents}{QDoc Manual}. \section1 Chapters \list 1 \li \l{Creating QDoc Configuration Files} \li \l{Writing Documentation} \li \l{Categories of Documentation} \li \l{Configuration File Example} \li \l{QML Documentation Example} \endlist */ /*! \page qdoc-guide-conf.html \title Creating QDoc Configuration Files \previouspage Getting Started with QDoc \nextpage Writing Documentation To generate documentation, QDoc uses configuration files, with the \c qdocconf extension, to store configuration settings. The \l{The QDoc Configuration File} article covers the various configuration variables in greater detail. \section1 QDoc Configuration Files QDoc's configuration settings can reside in a single \e qdocconf file, but can also be in other qdocconf files. The \c {include()} command allows configuration files to include other configuration files. QDoc has two outputs, HTML documentation and documentation in DITA XML format. The main distinction between the two outputs is that HTML documentation needs to have its HTML styling information in the configuration files. DITA XML documentation does not, and a separate process can style the documentation in DITA at a later time. DITA XML is therefore more flexible in allowing different styles to apply to the same information. To run qdoc, the project configuration file is supplied as an argument. \code qdoc project.qdocconf \endcode The project configuration contains information that qdoc uses to create the documentation. \section2 Project Information QDoc uses the \c project information to generate the documentation. \code project = QDoc Project description = Sample QDoc project \endcode \target qdoc-input-output-dir \section2 Input and Output Directories Specifying the path to the source directories allow QDoc to find sources and generate documentation. \code sourcedirs = exampledirs = imagedirs = sources.fileextensions = "*.cpp *.qdoc *.mm *.qml" headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx" examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml" examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng" \endcode QDoc will process headers and sources from the ones specified in the \c fileextensions variable. Likewise, QDoc needs the path to the output directory. The \c outputformats variable determines the type of documentation. These variables should be in separate configuration files to modularize the documentation build. \code outputdir = $SAMPLE_PROJECT/doc/html outputformats = HTML \endcode QDoc can resolve the paths relative to the qdocconf file as well as environment variables. \note During each QDoc run, the output directory is deleted. \section2 Extra Files QDoc will output generated documentation into the directory specified in the \l{Input and Output Directories}{output} directory. It is also possible to specify extra files that QDoc should export. \code extraimages.HTML = extraImage.png \ extraImage2.png \endcode The \c extraImage.png and the \c extraImage2.png files will be copied to the HTML output directory. \section2 Qt Help Framework Configuration QDoc will also export a \l{Qt Help Project} file, in a \c qhp file. The qhp file is then used by the \c qhelpgenerator to package the documentation into a \c qch file. Qt Creator and Qt Assistant reads the qch file to display the documentation. The \l {Creating Help Project Files} article covers the configuration options. \section2 HTML Configuration QDoc has an HTML generator that will export a set of documentation into HTML files using various configuration settings. QDoc will place the generated documentation into the directory specified by the \c outputdir variable. \code outputformats = HTML outputdir = \endcode QDoc needs to know where the styles and templates for generating HTML are located. Typically, the templates directory contains a \c scripts, \c images, and a \c style directory, containing scripts and CSS files. \code HTML.templatedir = \endcode The main configuration variables are: \code HTML.postheader HTML.postpostheader HTML.postheader HTML.footer HTML.headerstyles HTML.stylesheets = style.css \ style1.css HTML.scripts = script.js \endcode The \c{HTML.headerstyles} variable inserts the style information into the HTML file and the \c{HTML.stylesheets} specifies which files QDoc should copy into the output directory. As well, QDoc will embed the string in the \c postheader, \c footer, and related variables into each HTML file. The \l {HTML Specific Configuration Variables} article outlines the usage of each variable. \section2 DITA XML Configuration DITA XML output is enabled using the \c outputformats variable. Unlike HTML documentation, QDoc does not need HTML style templates for generating documentation in DITA XML format. \code outputformats = DITAXML outputdir \endcode \section2 Qt Index Reference Documentation projects can link to Qt APIs and other articles by specifying the path to the \c qt.index file. When qdoc generates the Qt Reference Documentation, it will also generate an index file, containing the URLs to the articles. Other projects can use the links in the index file so that they can link to other articles and API documentation within Qt. \code indexes =$QT_INSTALL_DOCS/html/qt.index \$OTHER_PROJECT/html/qt.index \endcode It is possible to specify multiple index files from several projects. \section1 Macros and Other Configurations Macros for substituting HTML characters exist and are helpful for generating specific HTML-valid characters. \code macro.pi.HTML = "Π" \endcode The snippet code will replace any instances of \c{\\pi} with \c Π in the HTML file, which will appear as the Greek \pi symbol when viewed in browsers. \section2 QML Additions QDoc is able to parse QML files for QDoc comments. QDoc will parse files with the QML extension, \c{.qml}, if the extension type is included in the \l{Input and Output Directories}{fileextensions} variable. Also, the generated HTML files can have a prefix, specified in the QDoc configuration file. \code outputprefixes = QML outputprefixes.QML = uicomponents- \endcode The outputprefixes will, for example, prefix QML type HTML filenames. \code files: uicomponents-button.html uicomponents-scrollbar.html \endcode */ /*! \page qdoc-guide-writing.html \title Writing Documentation \previouspage Creating QDoc Configuration Files \nextpage Categories of Documentation \section1 QDoc Comments Documentation is contained within qdoc \e comments, delimited by \beginqdoc and \endqdoc comments. Note that these are valid comments in C++, QML, and JavaScript. QDoc will parse C++ and QML files to look for qdoc comments. To explicitly omit a certain file type, omit it from the \l{Input and Output Directories}{configuration} file. \section1 QDoc Commands QDoc uses \e commands to retrieve information about the documentation. \c Topic commands determine the type of documentation element, the \c context commands provide hints and information about a topic, and \c markup commands provide information on how QDoc should format a piece of documentation. \target writing-topic-commands \section2 QDoc Topics Each qdoc comment must have a \e topic type. A topic distinguishes it from other topics. To specify a topic type, use one of the several \l{Topic Commands}{topic commands}. QDoc will collect similar topics and create a page for each one. For example, all the enumerations, properties, functions, and class description of a particular C++ class will reside in one page. A generic page is specified using the \l{page-command}{\\page} command and the filename is the argument. Example of topic commands: \list \li \l{enum-command}{\\enum} - for enumeration documentation \li \l{class-command}{\\class} - for C++ class documentation \li \l{qmlclass-command}{\\qmlclass} - for QML type documentation \li \l{page-command}{\\page} - for creating a page. \endlist The \l{page-command}{\\page} command is for creating articles that are not part of source documentation. The command can also accept two arguments: the file name of the article and the documentation type. The possible types are: \list \li \c howto \li \c overview \li \c tutorial \li \c faq \li \c article - \e default when there is no type \endlist \snippet examples/samples.qdocinc sample-faq The \l{Topic Commands} page has information on all of the available topic commands. \target writing-context \section2 Topic Contexts Context commands give QDoc a hint about the \e context of the topic. For example, if a C++ function is obsolete, then it should be marked obsolete with the \l{obsolete-command}{\\obsolete} command. Likewise, \l{nextpage-command}{page navigation} and \l{title-command}{page title}  give extra page information to QDoc. QDoc will create additional links or pages for these contexts. For example, a group is created using the \l{group-command}{\\group} command and the members have the \l{ingroup-command}{\\ingroup} command. The group name is supplied as an argument. The \l{Context Commands} page has a listing of all the available context commands. \target writing-markup \section2 Documentation Markup QDoc can do \e markup of text similar to other markup or documentation tools. QDoc can mark a section of text in \b{bold}, when the text is marked up with the \l{b-command}{\\b} command. \code \b{This} text will be in \b{bold}. \endcode The \l{Markup Commands} page has a full listing of the available markup commands. \section1 Anatomy of Documentation Essentially, for QDoc to create a page, there must be some essential ingredients present. \list \li Assign a topic to a QDoc comment - A comment could be a page, a property documentation, a class documentation, or any of the available \l{Topic Commands}{topic commands}. \li Give the topic a context - QDoc can associate certain topics to other pages such as associating obsolete functions when the documentation is marked with \l{obsolete-command}{\\obsolete}. \li Mark sections of the document with \l{Markup Commands}{markup commands} - QDoc can create layouts and format the documentation for the documentation. \endlist In Qt, the \l{QVector3D} class was documented with the following QDoc comment: \snippet examples/samples.qdocinc qvector3d-class It has a constructor, \l{QVector3D::QVector3D()}, which was documented with the following QDoc comment: \snippet examples/samples.qdocinc qvector3d-function The different comments may reside in different files and QDoc will collect them depending on their topic and their context. The resulting documentation from the snippets are generated into the \l{QVector3D} class documentation. Note that if the documentation immediately precedes the function or class in the source code, then it does not need to have a topic. QDoc will assume that the documentation above the code is the documentation for that code. An article is created using \l{page-command}{\\page} command. The first argument is the HTML file that QDoc will create. The topic is supplemented with context commands, the \l{title-command}{\\title} and \l{nextpage-command}{\\nextpage} commands. There are several other QDoc commands such as the \l{list-command}{\\list} command. \snippet examples/samples.qdocinc sample-page The section on \l{QDoc Topics}{topic commands} gives an overview on several other topic types. */ /*! \page qdoc-categories.html \title Categories of Documentation \previouspage Writing Documentation \nextpage Configuration File Example \brief Describes the different types such as How-To's, Tutorials, Overviews, Examples, and Class Documentation. There are several types of predefined documentation \e categories or \e types: \list \li How-To's \li Tutorial \li Overview \li Article \li FAQ (Frequently Asked Questions) \li C++ API Documentation \li QML Type Documentation \li Code Example \endlist QDoc has the ability to format a page depending on the type. Further, stylesheets can provide additional control on the display of each category. \section1 API Documentation QDoc excels in the creation of API documentation given a set of source code and documentation in QDoc comments. Specifically, QDoc is aware of Qt's architecture and can validate the existence of Qt C++ class, function, or property documentation. QDoc gives warnings and errors if it cannot associate a documentation with a code entity or if a code entity does not have documentation. In general, every Qt code entity such as properties, classes, methods, signals, and enumerations have a corresponding \l{qdoc-topics}{topic command}. QDoc will associate the documentation to the source using C++ naming rules. QDoc will parse the header files (typically \c .h files) to build a tree of the class structures. Then QDoc will parse the source files and documentation files to attach documentation to the class structure. Afterwards, QDoc will generate a page for the class. \note QDoc uses the header files to inform itself about the class and will not properly process QDoc comments in header files. \keyword qml-documentation \section2 Documenting QML Types In the world of \l{Qt Quick}{QML}, there are additional entities we need to document such as QML signals, attached properties, and QML methods. Internally, they use Qt technologies, however, QML API documentation requires different layout and naming conventions from the Qt C++ API documentation. A list of QML related QDoc commands: \list \li \l{qmlattachedproperty-command}{\\qmlattachedproperty} \li \l{qmlattachedsignal-command}{\\qmlattachedsignal} \li \l{qmlbasictype-command}{\\qmlbasictype} \li \l{qmlclass-command}{\\qmlclass} - creates a QML type documentation \li \l{qmlmethod-command}{\\qmlmethod} \li \l{qmlproperty-command}{\\qmlproperty} \li \l{qmlsignal-command}{\\qmlsignal} \li \l{inherits-command}{\\inherits} \li \l{qmlmodule-command}{\\qmlmodule} \li \l{inqmlmodule-command}{\\inqmlmodule} \endlist \note Remember to enable QML parsing by including the \c{*.qml} filetype in the \l{qdoc-input-output-dir}{fileextension} variable. To document a QML type, start by creating a QDoc comment that uses the \l{qmlclass-command} {\\qmlclass} command as its topic command. \section3 QML Parser If your QML type is defined in a \e qml file, document it there. If your QML type is represented by a C++ class, document it in the \e cpp file for that C++ class. Don't document a QML type in a \e{cpp} file if the QML type is defined in a \e{qml} file. When documenting a QML type in a \e{qml} file, place each QDoc comment directly above the entity to which the comment applies. For example, place the QDoc comment containing the \e{\\qmlclass} command (the topic comment) directly above the outer QML type in the \e{qml} file. Place the comment for documenting a QML property directly above the property declaration, and so on for QML signal handlers and QML methods. Note that when documenting QML properties in a \e{qml} file, you don't normally include the \e{\\qmlproperty} command as a topic command (which you must do when documenting QML types in \e{cpp} files), because the QML parser automatically associates each QDoc comment with the next QML declaration it parses. The same is true for QML signal handler and QML method comments. But it is sometimes useful to include one or more \e{\\qmlproperty} commands in the comment, e.g. when the property type is another QML type and you want the user to only use certain properties within that other QML type, but not all of them. But when documenting a property that has an alias, place the QDoc comment for it directly above the alias declaration. In these cases, the QDoc comment \e must contain a \e{\\qmlproperty} command, because that is the only way QDoc can know the type of the aliased property. When documenting a QML type in the \e cpp file of its corresponding C++ class (if it has one), you normally place each QDoc comment directly above the entity it documents. However, QDoc does not use the QML parser to parse these files (the C++ parser is used), so these QML QDoc comments can appear anywhere in the \e{cpp} file. Note that QML QDoc comments in \e cpp files \e must use the QML topic commands. i.e., the \l{qmlclass-command} {\\qmlclass} command \e must appear in the QDoc comment for the QML type, and a \l{qmlproperty-command} {\\qmlproperty} command \e must appear in each QML property QDoc comment. \section3 QML Modules A QML type belongs to a \e module. The module may include all the related types for a platform or contain a certain version of \l{Qt Quick}. For example, the Qt Quick 2 \l{QML Elements} belong to the QtQuick2 module while there is also a QtQuick1 module for the older types introduced in Qt 4. Modules affect the way QDoc link and relate the types. The \l{qmlclass-command}{\\qmlclass} topic command must have an \l{inqmlmodule-command}{\\inqmlmodule} context command to relate the type to a module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic command must exist in a separate \c .qdoc file to create the overview page for the module. The overview page will list the related types. The links to the QML types, must therefore, also contain the module name. For example, if a type called \c TabWidget is in the \c UIComponents module, it must be linked as \c {UIComponents::TabWidget}. The \l{componentset}{UIComponents} example demonstrates proper usage of QDoc commands to document QML types and QML modules. \section3 Read-only and Internal QML Properties QDoc detects QML properties that are marked as \c readonly. Note that the property must be initialized with a value. \code readonly property int sampleReadOnlyProperty: 0 \endcode For example, the example \l{TabWidget} type has a fictitious read-only property \c sampleReadOnlyProperty. Its declaration has the \c readonly identifier and it has an initial value. Properties and signals that are not meant for the public interface may be marked with the \l{internal-command}{\\internal} command. QDoc will not publish the documentation in the generated outputs. \section1 Articles & Overviews Articles and overviews are a style of writing best used for providing summary detail on a topic or concept. It may introduce a technology or discuss how a concept may be applied, but without discussing exact steps in too much detail. However, this type of content could provide the entry point for readers to find instructional and reference materials that do, such as tutorials, examples and class documentation. An example of an overview might be a product page, such as a top level discussion of QtQuick, individual modules, design principles, or tools. To signify that a document is an article, you append the article keyword to the \\page command: \snippet examples/samples.qdocinc sample-overview The \l{writing-topic-commands}{writing topic commands} section has a listing of the available \\page command arguments. \section1 Tutorials, How-To's, FAQ's Tutorials, How-To's, and FAQ's are all instructional material, in that they instruct or prescribe to the reader. Tutorials are content designed to guide the reader along a progressive learning path for a concept or technology. How-To's and FAQ's (\e{Frequently Asked Questions}) provide guidance by presenting material in the form of answers to commonly asked topics. How-To's and FAQ's are designed for easy reference and are not necessarily presented in a linear progression. To create these types, mark the pages by providing a \c type argument to the \l{page-command}{\\page} command. The \c type argument is the second argument, with the file name being the first. \snippet examples/samples.qdocinc sample-faq The \l{writing-topic-commands}{writing topic commands} section has a listing of the available \\page command arguments. \section1 Code Examples Examples are an effective way to demonstrate practical usage of a given technology or concept. When it comes to middleware this is usually in the form of an application using simple code and clear explanations of what the code is doing. Any module, API, project, pattern etc. should have at least one good example. An example may have an accompanying tutorial. The tutorial instructs and describes the code, while the code example is the code content that users may study. Code examples may have accompanying text that are not in the tutorial. QDoc will create a page containing the example code with a description using the \l{example-command}{\\example} command. \snippet examples/samples.qdocinc sample-example QDoc will use the directory specified in the input \l{Input and Output Directories}{exampledirs} variable to find the Qt Project (\c .pro) file to generate the example files. The generated HTML will have the filename, \c {declarative-ui-components-tabwidget.html}. QDoc will also list all of the example code. For reference, view QDoc's generated page for the \l{UI Components: Tab Widget Example}{Tab Widget} example. \note The example's project file must be the same as the directory name. */ /*! \example config \title Configuration File Example \previouspage Categories of Documentation \brief configuration files for the QDoc Manual and QDoc Guide The QDoc Manual uses these \c qdocconf files to generate the QDoc Guide and the \l{Table of Contents}{QDoc Manual}. \note The configuration files are similar to the Qt Reference Documentation and the QDoc Manual do not use all of the variables. The variables are included to demonstrate a full project scenario. \section1 Macros and other Definitions \list \li \l{config/compat.qdocconf} \li \l{config/macros.qdocconf} \li \l{config/qt-cpp-ignore.qdocconf} \li \l{config/qt-defines.qdocconf} \endlist QDoc allows macros to help with aliasing and for inputting special HTML characters within the documentation. Macros are a form of workarounds if QDoc is unable to resolve formatting issues such as when QDoc should disregard QDoc comments in documentation paragraphs. QDoc is also aware of the common C++ and Qt preprocessors and can decide which documentation to generate according to the definitions in the configuration files. \section1 Project Information \list \li \l{config/qdoc-online.qdocconf} \li \l{config/qdoc.qdocconf} \li \l{config/qdoc-project.qdocconf} \endlist These configuration files dictate how QDoc will generate the project. Depending which configuration file QDoc processes, the formatting and the information about the project will be different. If QDoc processes \c{qdoc-online.qdocconf}, QDoc will generate the HTML version of the manual will have the style suitable for online viewing. Additionally, the settings for creating the \l{The Qt Help Framework}{Qt Help File} is in the configuration. \note The project file uses variables used during Qt's \l{Configuration Options for Qt}{configuration} step. \section1 HTML Styles \list \li \l{config/qt-html-default-styles.qdocconf} \li \l{config/qt-html-online-styles.qdocconf} \li \l{config/qt-html-templates-online.qdocconf} \li \l{config/qt-html-templates.qdocconf} \endlist These files indicate which styles QDoc should use for the HTML formats. Typically, there are two templates, one for online viewing and one for offline. Qt Creator is able to fit more content in a page with the offline template. The templates store HTML information as strings and QDoc will copy the template to each HTML page. \section1 Project File \list \li \l{config/config.pro} \endlist Every example page (such as this one) needs a Qt project file. QDoc will use the project file to determine which files are part of the example. QDoc will then create a page listing all the files that are part of the example. \note the directory name of the example and the name of the project file must match. The example directory is found using the \l{qdoc-input-output-dir}{exampledirs} variable. */