API Documentation

For some reason I don't like the Javadoc concept of in-source comments for creating the documentation.
Instead of bloating my source code I want to keep the documentation in a separate file.
Consider some C++ source file func.cc that provides some functions or classes declared in func.h. Then doctool will create some doc-file stub func.doc.txt.
You see that the CODEREF box in the doc-file is logically linked with the declaration in the header file through the USR identifier below the box.
If you modify the function declaration in func.h the following happens:
- If you just modify the formation the CODEREF box gets updated.
- If you add a function to the header file func.h and a definition to the source file func.cc a new stub gets added to func.doc.txt.
- If you only add a declaration to func.h nothing happens. Because forward declarations are ignored.
- If you change the signature of a function or if you remove a function the CODEREF block becomes obsolete. doctool will stop and tell you where obsolete blocks are located. Unless you remove these blocks doctool will not go further (zero tolerance).
Some API documentation with a bit more text: dummy.h, dummy.cc and dummy.doc.

API documentation should be divided into three layers. Each layer goes into its own file:

myfunc.doc	Gives a general overview of the provided functionality, purpose, etc. It gives newbies the big picture. It also goes into detail. It basically contains everything important. Yes, it is hard to write good documentation that can achieve all of this. So in this file you really can focus on writing good documentation.
myfunc.h	Through its declarations and short comments it very briefly describes your interface. If more detail is needed go to myfunc.doc.
myfunc.cc	Comments in this file address other core developers. Hints in these comments deal with real inside knowledge, e.g. such a comment only makes sense to people that are involved.