Important: Please read the Qt Code of Conduct - https://forum.qt.io/topic/113070/qt-code-of-conduct

Using QDoc how can i append (not overwrite) content from a .qdoc file to content generated from .cpp files?



  • To begin, yes Ive been studying the QDoc help at http://doc-snapshot.qt-project.org/qdoc/qdoc-index.html, but i still have a lot of questions about the documentation process. The most critical one is in this topic title. The help implies I should be able to do this, but when i attempt to do so, i get a file created with the name Collision-myQMLType.html and a message in the cmd window, that reports that the file already exists.

    My config file has had various combinations of folders defined for headerdirs and sourcedirs. At best I have generated .html files for all the QMLTypes (when i omit my .qdoc files from the location defined in the config file). When i include the folder of .qdoc files, I get only the number of html files that correspond with the number of qdoc files. Here is a sample of one of my config files.

    outputdir = ./output/html
    headerdirs = ./sourcecodedir
    sourcedirs = ./qdocdir
    imagedirs = ./images
    sources.fileextensions = "*.cpp *.qdoc *.qml"

    How do i ensure the information from the .qdoc files APPENDS the information from the .cpp files?



  • I think there is a conceptual misunderstanding here. qdoc treats .cpp and .qdoc files pretty much as the same. If you get conflicts it is because you document a class/function/etc twice.



  • so does that mean there is no way to have content for a single class / function come from two different files?

    as well as attempting to merge content between .cpp files and .qdoc, we also have a case where we have c++ classes already documented in .h files, and we are now added qml wrappers to these c++ classes. instead of rewriting the help again for the newly exposed qml components, we would like to inherit as much of the c++ help content as possible. is there a precedent for this?


  • Lifetime Qt Champion

    Hi,

    No, it means that you have duplicated documentation. You can have the documentation of a class spread across several files (e.g. the header and the implementation files) but you should not have this documentation copied multiple times (.i.e only document a function once).



  • hmm... thank you both. im still struggling with the difference between spreading the documentation and duplicating it.

    in my cpp file i have a class called MyTable, so i have a qdoc comment preceding it like this:

      \qmltype MyTable
    

    then in my qdoc file i also have qdoc comments that start with

      \qmltype MyTable
    

    to act as the link. is this correct?


  • Lifetime Qt Champion



  • ok so this is interesting. \ref appears to be a doxygen command but not a qdoc command. for others reviewing this thread the qdoc commands are here
    http://doc-snapshot.qt-project.org/qdoc/27-qdoc-commands-alphabetical.html

    i looked for something similar - tried \page and it still didn't work. is the implication here that i should be about use different commands in different files but all refer to the same class?


Log in to reply