Motivation for not putting documentation comments in headers

Kerndog73

The Qt headers do not contain documentation comments. The documentation is embedded in the sources (but I don't have the sources so I don't know). If I want to know what a function does, I have to leave the IDE and look it up.

Why does it have to be this way? It's annoying. It slows down my workflow (because I'm still learning how to use Qt). Is there a good reason for doing things differently to other libraries?

Christian Ehrlicher

Use Qt creator, mark the class/function you want the help for and press F1. Or wait for the tooltip.

JKSH

Hi @Kerndog73, and welcome!

@Kerndog73 said in Motivation for not putting documentation comments in headers:

If I want to know what a function does, I have to leave the IDE and look it up.

You can look it up within the IDE; no need to leave it. Just hover your mouse cursor over the function (in your own code or in the header file) and press F1. When you've finished reading, press Esc to close the documentation pane.

EDIT: @Christian-Ehrlicher beat me to it!

The Qt headers do not contain documentation comments. The documentation is embedded in the sources (but I don't have the sources so I don't know)....

Why does it have to be this way?.... Is there a good reason for doing things differently to other libraries?

I believe the F1 approach provides a smoother workflow than having to open the header files.

Also, Qt documentation is extremely comprehensive (see line #1006 onwards, for example: https://code.woboq.org/qt5/qtbase/src/corelib/kernel/qobject.cpp.html#1006 ) Putting all this documentation in the headers would make them absolutely massive.

Kerndog73

I'm not using Qt Creator. I guess I'm gonna have to start using all of the Qt tools like moc, qmake and Qt Creator even though I've been able to get on fine without them.

SGaist

Hi,

Or you can use the online documentation or use Qt's Assistant.

JKSH

@Kerndog73 said in Motivation for not putting documentation comments in headers:

I'm not using Qt Creator.

Sorry, I shouldn't have assumed you were.

I guess I'm gonna have to start using all of the Qt tools like moc, qmake and Qt Creator even though I've been able to get on fine without them.

You can use Qt without Qt Creator or qmake, but moc is a core part of Qt: Your ability to subclass QObject-based classes will be limited without moc.

The other supported IDE is Visual Studio, via the Qt VS Tools.
The other supported build manager is CMake. (There is also Qbs but the Qt Company is no longer actively developing it)
There is no replacement for moc

Do give Qt Creator a try. It has lots of features to improve workflow with Qt-based projects:

Integrated documentation
Integrated example projects
Integrated WYSIWYG editors for GUIs written in both C++ (Qt Widgets) and QML (Qt Quick)
Integrated profiler for QML code
Various templates for creating new projects or classes
Syntax highlighting and code completion for Qt-specific features
It automatically runs moc and other Qt tools -- you don't have to run them manually

Kerndog73

@JKSH I installed Qt Creator. I can see the benefits of using this for creating Qt applications. However, switching IDEs is an incredibly jarring experience. Trying to migrate my project to a Qt Creator project was painful. Xcode was working fine and I'm used to it. Using Qt Creator from the beginning would have made a lot more sense.

I'll definitely use Qt Creator for my next Qt project.