[cfe-dev] libclang based non-doxygen/javadoc-style tool

[Michael Lehn]

Am 17.08.2012 um 20:07 schrieb Konstantin Tokarev:

> 
> 
> 17.08.2012, 21:18, "Michael Lehn" <michael.lehn at uni-ulm.de>:
>> Hi,
>> 
>> libclang is really a great tool for writing your own documentation tool.  I
>> never liked the concept of javadoc/doxygen of putting all the documentation
>> into the header/source files.  In my opinion it bloats the headers and makes
>> them unclear.
> 
> However, it's easier to keep in-source documentation up to date.

The first time I was using javadoc I had the same thought.  I was thinking
that putting the documentation directly to the crime scene is the right thing
to do "... when I change the function I update the documentation next to it...".

But then I ended up with "... let's just fix the code quickly and update the
documentation later ...".  And I ended up with documentation comments that were
not in sync with the code.  So I learnt that no tool will do all the work for me.
But maybe I am the only one having this problem.

Anyway, from some point of view my documentation tool is doing the same thing as
javadoc/doxygen.  Assume I have some file 'myfunc.h' with a function 'void dummy()'.
Then I my tool creates (or updates) some file 'myfunc.doc'.  This file will contain
some documentation-stub, that looks like this:

 *--[CODEREF]-----------*
 |                      |
 | void dummy();        |
 |                      |
 *----------------------*
                 [...USR]

The code snippet for 'void dummy()' is *logically linked* with the function's
declaration through the USR generated by libclang.  So whether I put my documentation
at the 'myfunc.doc' file beside its CODEREF location or put it at its original place
in 'myfunc.h' is logically equivalent.  However, physically its separated clean and tidy.

At least for editors like VIM it is fairly easy to write a plugin such that you can jump
from the source-file to the doc-file forth and back.  E.g. if your in 'myfunc.h' at the
'dummy' declaration you jump to the 'myfunc.doc' to corresponding CODEREF section.  Or it
can create a new CODEREF snippet it doesn't already exist.

If the signature of a function changes my tool detects that the doc-file contains
obsolete documentation.  This is something javadoc/doxygen can not do.

Michael