17.08.2012, 21:18, “Michael Lehn” <michael.lehn@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
cfe-dev mailing list
cfe-dev@cs.uiuc.edu
http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
I must admit that the .doc file looks pretty weird (format-wise), especially the —[XXX]— parts, with | delimiters etc… but after looking at all the different things that can go within it, I suppose it makes (some) sense. I would still advise to make it more lightweight by removing the trailing | (and blanks), something as light as:
[CODE]
// some code example
Would be at least as simple to parse and be much easier to compose manually.
Otherwise, it does seem like a great tool. The debate for in-source vs out-of-source documentation has been raging for a while already and though I initially appreciated in-source documentation like you I have found that there are issues; my personal peeve is the amount of screen estate “lost”: when I am looking for a function, having only 3 signatures per screen because each is preceded by a large (mostly auto-generated and mind-numbing) doyxgen stub is extremely annoying.
Is this tool available somewhere ?
– Matthieu
