how to document classes and member functions?

[jackal]

I'm having problems with writing documentations for my classes and their member functions. I've found what I want in Qt base classes. Here are several rows from "QVector.cpp":


/*!
\class QVector
\brief The QVector class is a template class that provides a dynamic array.

\ingroup tools
\ingroup shared

\reentrant

QVector\<T\> is one of Qt's generic \l{container classes}. It
stores its items in adjacent memory locations and provides fast
index-based access.

QList\<T\>, QLinkedList\<T\>, and QVarLengthArray\<T\> provide
similar functionality. Here's an overview:

\list
\i For most purposes, QList is the right class to use. Operations
like prepend() and insert() are usually faster than with
..........
*/

/*!
\fn QVector<T> QVector::mid(int pos, int length = -1) const

Returns a vector whose elements are copied from this vector....
.........
*/
// ....



When I'm trying to do the same in my ".cpp" files, nothing happens (hovering the functions' calls in other files doesn't show my documentation). I tried to find some documentation about this and the keywords (tags) as well (like "\class", "\brief", "\ingroup"...), but I couldn't find anything. Can anyone help or give any links to documentation concerning this?

[mcosta]

HI,

Qt uses doxygen for documenting the code.

See here (http://www.stack.nl/~dimitri/doxygen/manual.html) for details.

[jackal]

Qt uses doxygen for documenting the code.


Yes, that's very good solution for me. But my main problem is to make Qt Creator to show my brief descriptions when hovering the described functions or other members. It's useful for others to view it exactly in the cpp files, while working on those.

[mcosta]

Read here (http://doc.qt.nokia.com/4.7/assistant-custom-help-viewer.html) to integrate your doc into QtAssistant.

I think QtCreator uses it

[jackal]

According to what I've found there, it's possible to create a custom documentation and register it in both Qt Creator and Assistant. But it's not project-based. It's hard and boring work witch is useful for types that can be used in any project. All I wanna do is to describe each project's parts (classes, variables, functions...) individually.

[mcosta]

If you want use Qt Creator, you must use Assistant integration.

I think this is not so hard and can be usefull for developing big projects.

[jackal]

I think this is not so hard and can be usefull for developing big projects.

Agree, but in any job there will always be types that have the same name, but different purposes in different projects (I'm talking about small classes, that doesn't mean to be used everywhere with same functionality). I'm almost sure there will be solutions for cases like this: to create fast, small, project-depended documentation (like with doxygen, but integrated in Qt Creator for specific project only).
Anyway, your help was very useful. Thank you very much! If I find smth about this in future, I'll post it here for everyone.

[jackal]

Problem partly solved!

To use your own documentation in Qt Assistant (and in Qt Creator help as well) you need to create Qt Compressed Help file (.qch (http://doc.qt.nokia.com/4.7/assistant-custom-help-viewer.html#displaying-custom-documentation)) and register it in Assistant and Creator.
Doxygen has several tools exactly for Qt. There are tags in it's config file, that help you to create the documentation exactly the way you need. E.g. with GENERATE_QHP tag you can make it create the ready qhp (http://doc.qt.nokia.com/4.7/assistant-custom-help-viewer.html#creating-a-custom-help-collection-file) (Qt Help Project) file (you need this to generate the .qch). If you don't need to edit this file manually before creating the .qhc, you can set the value of QHG_LOCATION tag to the location of your qhelpgenerator.exe (usually it's here (in Windows): <QtPath>/mingw/bin/qhelpgenerator.exe) and it will generate the ready documentation. Register it in Qt Assistant (optional) and Creator and you're done.
After this all your documented types, functions, members, etc. will have the tooltip with F1 button hint. And of course pushing F1 will show your documented help for it.

Now the only problem remaining is to make Qt Creator to show also the brief descriptions. I've tried a lot but useless.. If anyone have an idea, please tell me.

[mcosta]

Have you used "QT_AUTOBRIEF"???

[jackal]

Have you used "QT_AUTOBRIEF"???

Yes, it didn't help :(

[mcosta]

ok, I think this is a question for Qt Creator gurus (developer)

[jackal]

Qt Creator gurus (developer)

are there any in this forum?

[squidge]

I don't think Qt supports project-specific help whilst you type, but there are IDEs that do, such as Netbeans, Visual Studio (with plugin) and possibly Eclipse. Netbeans being my current favorite, free, open source and easily extendable with Java.

[mcosta]

I saw Qt Creator code and I understand (I hope) that it uses the index.

[jackal]

Thank you for your help, guys! I think it's good idea to try Netbeans (I don't want new headaches about this any more right now). After I finish my current project, I'll try to find some solution to use native tooltips of Qt Creator. I'll let you know if I have any success.

[jackal]

I think it's good idea to try Netbeans
NOPE! I didn't like it :(
Qt Creator is really good. Don't wanna try another editor