Documentation Tool Recommendation Required



  • I am looking for a good tool for helping me in documentation (Class diagrams, Sequence Diagrams etc). My team is required to follow waterfall model and hence we are required to document everything; every function, every variable. Since we are required to do this for every stage, I wanted some tool to help me do the work [or rather do this boring work for me].

    I tried Enterprise Architect, but it doesn't recognize signals and slots, making the output not exactly ideal. I looked it up and I read that there is no support for integration of EA with Qt.

    Searching the net landed me stuff like NCReport C++/Qt Report Generator and Doxygen as the top results. I honestly don't have any experience with either of them.

    So, I wanted to know what tool is used/recommended by you guys and why you use/recommend it.


  • Qt Champions 2016

    My vote goes to Doxygen
    Reason:

    • Easy to use
    • Easy to setup.
    • Easy to tweak
    • You can use only minimal tagging. ( non very intrusive)
    • Its free software and source is available ( no lock down)
    • So far it worked very well with Qt
    • It has many types of diagram
    • Huge User base. ( many to ask/questions solved)

    It also have a plugin for Creator
    https://wiki.qt.io/Doxygen_Plugin_for_QtCreator
    (I have not tested it as I use mingw and have no VS installed)

    If you want to spend as little time as possible, its a time saver to create the different comment styles (tag)
    as text snippets for fast insertion. :)


  • Qt Champions 2016

    @Vader
    This would really be a question of preference more than anything. However, Qt uses Doxygen qdoc (which is similar to Doxygen) for building its documentation, so I suppose that'd be "recommended" if such label can be applied at all. I'd used Doxygen in the past and I'm not very impressed by the easiness or the workflow, but it does work as one would expect and it does have the necessary capabilities.



  • @kshegunov said:

    Qt uses Doxygen for building its documentation

    Is that actually true? I've seen it implied and suggested a few times, discussed on the mailing lists etc, but I've never found a definitive reference for it being so. Just curious myself :)


  • Qt Champions 2016

    @Paul-Colby
    I have to check the build scripts to be completely sure that some magic is not employed, but these comments in the source sure look like Doxy syntax.



  • @kshegunov said:

    these comments in the source sure look like Doxy syntax.

    Yeah, but they also look like QDoc commands.

    My understanding (which is very limited), is that Qt began with QDoc years ago, which then inspired the creation of Doxygen. There's since been plenty of comments re Qt moving to Doxygen one day, but I have no idea if that has already happened, is currently in progress, or just planned for one day in the future?

    Doxygen is great either way (I use it a lot). I was just curious to know if Qt had officially moved to it yet :)

    Cheers.


  • Qt Champions 2016

    @Paul-Colby

    Yeah, but they also look like QDoc commands.

    Fair enough. It's (quite) possible I'm just mistaken, especially as it seems qdoc provides its own parser, so I suppose qdoc is the tool used.


  • Lifetime Qt Champion

    Hi,

    Yes, it's still qdoc that's used, it's also been updated for the QML documentation.


Log in to reply
 

Looks like your connection to Qt Forum was lost, please wait while we try to reconnect.