From Qt Wiki
Jump to navigation Jump to search

QDoc (AKA qdoc3) is the currently available configurable documentation generation tool. QDoc is used to generate the Qt Reference Documentation. The documentation is part of the version dependent documentation of Qt, see: http://doc.qt.io/qt-5/qdoc-index.html.

Current features

  • Supports C++ and QML input.
  • Supports HTML and DITA XML output.
  • Possibility to link multiple documentation packages together using index files.

Future changes

It is hard to maintain and implement new features in qdoc3. qdoc3 is currently also not able to generate properly modularized Qt reference documentation. Therefore some work is required to future-proof QDoc. This will probably require a rewrite of significant parts of QDoc.

Proposed changes are:

  • Rename qdoc3 to just qdoc.
  • Make it possible to run QDoc on a single file.
  • Convert QDoc to an architecture which uses plugins. This would make it possible to ship plugins with their respective modules (ship qdoc-base in qtbase and the QML parsing plugin in QtDeclarative). It would then also be possible to easily implement plugins for different input/output formats and different.
  • Use a proper C++ parser. Currently qdoc3 tries to use some tricks to generate documentation. qdoc3 for instance does not expand macros, which means that a macro has to be added to an ignore list to skip parsing the macro. A solution could be to use the Abstract Syntax Tree-parser which is used by Qt Creator. That parser properly expands macros and would make using ignore lists obsolete.
  • Make it possible to run QDoc on individual modules, merging the content afterwards if requested.
  • Merge the Generator and PageGenerator classes, these classes were used separately for QtJambi, but now All generators are a subclass of PageGeneratr, which is a subclass of Generator.

Requested Features

See also development@qt.io, RFC: The Future of QDoc

  • Make it possible to have documentation in headers
  • Enums should be documented in the header inline (doxygen style)
  • Have Qt Creator be able to build the docs as target