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

[Matthieu Monrocq]

On Fri, Aug 17, 2012 at 9:41 PM, Michael Lehn <michael.lehn at uni-ulm.de>wrote:

> 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
>
>
>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120818/82fb4b5b/attachment.html>