Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-103366

QDoc doesn't generate all the documentation.

    XMLWordPrintable

Details

    • Bug
    • Resolution: Out of scope
    • P3: Somewhat important
    • None
    • 6.2.4
    • Build tools: qdoc
    • None
    • Qt 6.2.4 with Qt Creator 7.0.1 with MSVS 2019 x64 as build toolchain in a Windows 10 and Windows 11 virtual machine.
    • Windows

    Description

      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 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(int newMaxLogsToKeep), 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 error as output1.png .

      And the actual HTML is like files output2.png and output3.png .

      As you can see, it misses several class members and I don't know why.

      Another funny thing is that even if I changed, in my .qdocconf the project name, in the output HTML I have (in the "since" field) the Qt name.

      Lastly, if I try to remove the

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

      I got the error on the output4.png file.

      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

      Attachments

        1. output1.png
          output1.png
          191 kB
        2. output2.png
          output2.png
          38 kB
        3. output3.png
          output3.png
          22 kB
        4. output4.png
          output4.png
          193 kB
        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

        Activity

          People

            docinfrastructure Documentation Infrastructure Team
            anandir Giacomo Succi
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved:

              Gerrit Reviews

                There are no open Gerrit changes