QDoc doesn't generate all the documentation.

[Anandir]

Good evening,
I'm a newbie with Qt and I've embarked myself on a quite big project with the purpose of "learn-by-doing" Qt.
So far so good, but I've encountered a problem with QDoc.
I've written a few classes so far and I've begun to QDoc 'em all, but when I generate the QDoc files, they miss a lot of information.

Here it is my .qdocconf file:

project                = WinAfrho3
description            = Documentation of the WinAfrho 3.0 project.
version                = 0.1
url                    = http://cara.uai.it/

sourcedirs             = ./src
headerdirs             = ./src/include
includepaths           = ./src \
                         C:/Qt/6.2.4/msvc2019_64 \
                         C:/Qt/6.2.4/Src
imagedirs              = ./src/doc/images

sources.fileextensions = "*.cpp *.c *.qdoc"
headers.fileextensions = "*.h *.h++ *.hh *.hpp *.hxx"
#examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"

navigation.landingpage = "Welcome to the WinAfrho 3.0 documentation."

outputdir              = ./docs
outputformats          = HTML

HTML.stylesheets       = ./src/doc/offline.css
HTML.headerstyles      = "<link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\"/>\n"

Here's an example of a class:
"logging/filelogger.h":

#ifndef FILELOGGER_H
#define FILELOGGER_H

#include <QObject>
#include <QDebug>
#include <QDir>
#include <QFile>
#include <QFileInfo>
#include <QStringList>

#include "winafrho.h"

class FileLogger : public QObject
{
		Q_OBJECT
	public:
		explicit FileLogger(QObject *parent, QString filePath);
		~FileLogger();

		int getMaxLogsToKeep() const;
		void setMaxLogsToKeep(int newMaxLogsToKeep);

	public slots:
		void lineAdded(QtMsgType type, QString message);

	private:
		QString logFilePath;
		QFile *logFile;
		QTextStream *logStream;
		int maxLogsToKeep = 5;
};

#endif // FILELOGGER_H

"logging/filelogger.cpp":

#include "logging/filelogger.h"

/*!
	\class FileLogger
	\brief The FileLogger class implementing the logging in a file logic.
	\inmodule winafrho3
	\since 0.1

	The \c FileLogger class is responsible save all the log messages in a file.
 */

/*!
	\fn FileLogger::FileLogger(QObject *parent, QString filePath)
	\since 0.1

	Is the constructor for the file logging class and connect it to the \a parent ,
	for memory management.
	It needs a \a filePath where it should save the all the catched logs.
	It keeps a certain amount of old logs, by default are 5. This can be changed
	with the \c setMaxLogsToKeep() function.

	\sa setMaxLogsToKeep(), getMaxLogsToKeep()
 */
FileLogger::FileLogger(QObject *parent, QString filePath) : QObject{parent}
{
	this->logFilePath = filePath;

	if (QFile::exists(filePath))
	{
		QString newFileName = filePath;
		QFileInfo info = QFileInfo(this->logFilePath);
		QDir dir = info.absoluteDir();

		QStringList filters;
		filters << "*.log.*";
		dir.setNameFilters(filters);

		QStringList lst = dir.entryList();

		qsizetype lst_size = lst.size();

		if (lst_size >= this->maxLogsToKeep)
		{
			QString tmp1 = filePath + ".0";
			QString tmp2 = "";

			QFile::remove(tmp1);

			for (int i = 1; i < 5; i++)
			{
				tmp1 = filePath + "." + QString::number((i - 1));
				tmp2 = filePath + "." + QString::number(i);

				QFile::rename(tmp2, tmp1);
			}

			lst_size -= 1;
		}

		newFileName += "." + QString::number(lst_size);

		QFile::rename(filePath, newFileName);
	}

	this->logFile = new QFile(this->logFilePath, this);
	this->logFile->open(QFile::WriteOnly | QFile::Truncate);

	if (this->logFile->isOpen())
	{
		this->logStream = new QTextStream(this->logFile);
		this->logStream->setEncoding(QStringConverter::Encoding::Utf8);
	}

	// Wire up the logger
	QObject::connect(applicationLogger->theLogger, &LoggingHandler::logLineAdded,
					 this, &FileLogger::lineAdded);
}

/*!
	\fn FileLogger::~FileLogger()
	\since 0.1

	Destroyer of the class.
 */
FileLogger::~FileLogger()
{
	QObject::disconnect(applicationLogger->theLogger, &LoggingHandler::logLineAdded,
						this, &FileLogger::lineAdded);

	this->logFile->close();
	delete(this->logStream);
}

/*!
	\fn void FileLogger::lineAdded(QtMsgType type, QString message)
	\since 0.1

	This is the slot called by the \c LoggingHandler::logLineAdded signal.
	It append the log to the log file in the standard format.

	The standard format is, in example:

	\code
		[INFO] [24/04/2022 13:35:38.3603636] - void __cdecl translationsLoad(class QApplication &) - Initialization translation start...
		[INFO] [24/04/2022 13:35:38.365365365] - void __cdecl translationsLoad(class QApplication &) - Initialization translation ended.
		[DBG] [24/04/2022 13:35:38.367367367] - void __cdecl styleSetup(class QApplication &) - Initialization style start...
		[DBG] [24/04/2022 13:35:38.368368368] - void __cdecl styleSetup(class QApplication &) - Initialization style ended.
		[DBG] [24/04/2022 13:35:38.368368368] - void __cdecl loadFonts(class QApplication &) - Custom fonts load start...
		[DBG] [24/04/2022 13:35:38.368368368] - void __cdecl loadFonts(class QApplication &) - CourierPrime-Bold load...

		...
	\endcode

	It requires a message \a type and the actual \a message.

	\sa LoggingHandler::logLineAdded
 */
void FileLogger::lineAdded(QtMsgType type, QString message)
{
	if (this->logFile == NULL)
		return;

	if (!this->logFile->isOpen())
		return;

	if (this->logStream == NULL)
		return;

	QString line = "";

	switch (type) {
		case QtInfoMsg:
			line = "[INFO] ";
			break;
		case QtDebugMsg:
			line = "[DBG] ";
			break;
		case QtWarningMsg:
			line = "[WARN] ";
			break;
		case QtCriticalMsg:
			line = "[CRT] ";
			break;
		case QtFatalMsg:
			line = "[FATAL] ";
			break;
	}

	line += message;

	*(this->logStream) << line << "\r\n";
	this->logStream->flush();
}

/*!
	\fn int FileLogger::getMaxLogsToKeep() const
	\since 0.1

	Returns the actual amount of logs to keep.
 */
int FileLogger::getMaxLogsToKeep() const
{
	return maxLogsToKeep;
}

/*!
	\fn void FileLogger::setMaxLogsToKeep(int newMaxLogsToKeep)
	\since 0.1

	Set the \a newMaxLogsToKeep , the actual amount of logs to keep.
 */
void FileLogger::setMaxLogsToKeep(int newMaxLogsToKeep)
{
	this->maxLogsToKeep = newMaxLogsToKeep;
}

But when I generate the QDoc I get this output:

And the output file is:

As you can see, it misses several class members and I don't know why.
Do you have any ideas?

I use Qt 6.2.4 with Qt Creator 7.0.1 with MSVS 2019 x64 as build toolchain.

Thanks a lot in advance!

Best regards
Giacomo

[kkoehne]

@Anandir said in QDoc doesn't generate all the documentation.:

As you can see, it misses several class members and I don't know why.
Do you have any ideas?

The code looks correct to me. You can maybe work around the problem though by just removing

\fn void FileLogger::lineAdded(QtMsgType type, QString message)

and friends. qdoc is clever enough that, if you do not give an explicit \fn, the documentation is associated with the following C++ function. So you need an explicit \fn usually only for inline functions that are defined in a header.

[Anandir]

@kkoehne said in QDoc doesn't generate all the documentation.:

@Anandir said in QDoc doesn't generate all the documentation.:

As you can see, it misses several class members and I don't know why.
Do you have any ideas?

The code looks correct to me. You can maybe work around the problem though by just removing

\fn void FileLogger::lineAdded(QtMsgType type, QString message)

and friends. qdoc is clever enough that, if you do not give an explicit \fn, the documentation is associated with the following C++ function. So you need an explicit \fn usually only for inline functions that are defined in a header.

First of all, thanks for your kind reply!
While I was looking for a solution, I've found this walkaround somewhere and tried that too.
To be fair, I've also looked at some Qt classes and noticed that. That if the comment is right above the function, QDoc will "use" the function as original \fn, like you've mentioned.
But it doesn't work. Instead, I have another error.
To be on the same page, I've modified my QDoc comment like that:

/*!
    \since 0.1

	This is the slot called by the \c LoggingHandler::logLineAdded signal.
	It append the log to the log file in the standard format.

	The standard format is, in example:

	\code
		[INFO] [24/04/2022 13:35:38.3603636] - void __cdecl translationsLoad(class QApplication &) - Initialization translation start...
		[INFO] [24/04/2022 13:35:38.365365365] - void __cdecl translationsLoad(class QApplication &) - Initialization translation ended.
		[DBG] [24/04/2022 13:35:38.367367367] - void __cdecl styleSetup(class QApplication &) - Initialization style start...
		[DBG] [24/04/2022 13:35:38.368368368] - void __cdecl styleSetup(class QApplication &) - Initialization style ended.
		[DBG] [24/04/2022 13:35:38.368368368] - void __cdecl loadFonts(class QApplication &) - Custom fonts load start...
		[DBG] [24/04/2022 13:35:38.368368368] - void __cdecl loadFonts(class QApplication &) - CourierPrime-Bold load...

		...
	\endcode

	It requires a message \a type and the actual \a message.

	\sa LoggingHandler::logLineAdded
 */
void FileLogger::lineAdded(QtMsgType type, QString message)
{

It's exactly the same, but without the \fn declaration.
And this is what I have as result.

And, above that, it cannot "link" functions that are present in the actual class...

And that's why I'm totally confused 😖.

Again, thanks a lot in advance.
Best regards,
Giacomo

[kkoehne]

MMh .. sounds indeed that something goes wrong here, then.

Can you create a somewhat minimal example, and open a bug report at https://bugreports.qt.io/projects/QTBUG, component 'Build tools: qdoc'?

[Anandir]

@kkoehne said in QDoc doesn't generate all the documentation.:

MMh .. sounds indeed that something goes wrong here, then.

Can you create a somewhat minimal example, and open a bug report at https://bugreports.qt.io/projects/QTBUG, component 'Build tools: qdoc'?

Sure!
I'll prepare something. Maybe it's a particular configuration that leads to some kind of problem.

Thanks a lot in advance.

I'll keep you posted :-)!