<br><br><div class="gmail_quote">On Fri, Aug 17, 2012 at 9:41 PM, Michael Lehn <span dir="ltr"><<a href="mailto:michael.lehn@uni-ulm.de" target="_blank">michael.lehn@uni-ulm.de</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Am 17.08.2012 um 20:07 schrieb Konstantin Tokarev:<br>
<div class="im"><br>
><br>
><br>
> 17.08.2012, 21:18, "Michael Lehn" <<a href="mailto:michael.lehn@uni-ulm.de">michael.lehn@uni-ulm.de</a>>:<br>
>> Hi,<br>
>><br>
>> libclang is really a great tool for writing your own documentation tool.  I<br>
>> never liked the concept of javadoc/doxygen of putting all the documentation<br>
>> into the header/source files.  In my opinion it bloats the headers and makes<br>
>> them unclear.<br>
><br>
> However, it's easier to keep in-source documentation up to date.<br>
<br>
</div>The first time I was using javadoc I had the same thought.  I was thinking<br>
that putting the documentation directly to the crime scene is the right thing<br>
to do "... when I change the function I update the documentation next to it...".<br>
<br>
But then I ended up with "... let's just fix the code quickly and update the<br>
documentation later ...".  And I ended up with documentation comments that were<br>
not in sync with the code.  So I learnt that no tool will do all the work for me.<br>
But maybe I am the only one having this problem.<br>
<br>
Anyway, from some point of view my documentation tool is doing the same thing as<br>
javadoc/doxygen.  Assume I have some file 'myfunc.h' with a function 'void dummy()'.<br>
Then I my tool creates (or updates) some file 'myfunc.doc'.  This file will contain<br>
some documentation-stub, that looks like this:<br>
<br>
 *--[CODEREF]-----------*<br>
 |                      |<br>
 | void dummy();        |<br>
 |                      |<br>
 *----------------------*<br>
                 [...USR]<br>
<br>
The code snippet for 'void dummy()' is *logically linked* with the function's<br>
declaration through the USR generated by libclang.  So whether I put my documentation<br>
at the 'myfunc.doc' file beside its CODEREF location or put it at its original place<br>
in 'myfunc.h' is logically equivalent.  However, physically its separated clean and tidy.<br>
<br>
At least for editors like VIM it is fairly easy to write a plugin such that you can jump<br>
from the source-file to the doc-file forth and back.  E.g. if your in 'myfunc.h' at the<br>
'dummy' declaration you jump to the 'myfunc.doc' to corresponding CODEREF section.  Or it<br>
can create a new CODEREF snippet it doesn't already exist.<br>
<br>
If the signature of a function changes my tool detects that the doc-file contains<br>
obsolete documentation.  This is something javadoc/doxygen can not do.<br>
<span class="HOEnZb"><font color="#888888"><br>
Michael<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
<br>
<br>
_______________________________________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@cs.uiuc.edu">cfe-dev@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev</a><br>
</div></div></blockquote></div><br>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:<br>
<br>| [CODE]<br>| // some code example<br>|<br><br>Would be at least as simple to parse and be much easier to compose manually.<br><br>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.<br>
<br>Is this tool available somewhere ?<br><br>-- Matthieu<br>