Hi,

A library of mine has doxygen documentation, which I know works when processed externally with doxygen, as you can see the output here: http://staropram.github.io/cantcoap/index.html

But I can't figure out how to get this to show up in the API documentation here http://mbed.org/users/ashleymills/code/cantcoap/docs/tip/

I've tried right clicking on my cpp file (or the library) and selecting the compile option "Update Docs", but this doesn't seem to do anything. Am I missing something obvious?

Note that in this case I didn't put the doxygen in the header file, only in the cpp file, but this works with the normal doxygen tool.

Ashley

In my experience the mbed doxygen uses only the header file. Also make sure you have documented the Class declaration itself and not just the methods otherwise all info is ignored.

It also makes sense to document it in the header file: That is where the functions are defined and what you 'give' to a user, the cpp files can be a black box for the user.

Well it's debatable.

The reason I prefer to put it in the cpp file is because as a classic c programmer, I'm used to looking in the header file for a concise summary of the library or class. If you want to get an understanding of the class structure, it's a lot easier to look at it without all the function documentation in it (I would normally only put class structure doxygen there). Otherwise it is spread out too much.

Since doxygen generates a comprehensive documentation, then there isn't need for having anything in the header file, so putting it in the cpp normally serves two needs:

1. Classic c programmers and hardcore people can just look at the header file, which for simple things is going to be sufficient
2. Everyone else can look at the doxygen

I think it also makes sense to have the comprehensive docs in the cpp file, so that if you goto examine the guts of a function, then the details of the function are right there, rather than being in a separate file.

There are other reasons and a big debate about it here: http://stackoverflow.com/questions/355619/where-to-put-the-doxygen-comment-blocks-for-an-internal-library-in-h-or-in-cpp :D

In anycase, IMO if mbed wants to be truly compatible with doxygen then it should definitely parse cpp files and extract documentation from there as well as from header files, since that's what doxygen supports.