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

[Michael Lehn]

Am 18.08.2012 um 11:32 schrieb Matthieu Monrocq:
> 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),

As an alternative, more lightweight notation I already have

--- CODE -----------
// some code example 
--------------------

Only the 3 dashes before and after CODE are required (the rest is optional).  The block must
be ended with at least 6 dashes.  The indent of "--- CODE ---" and "------" has to match.
As code snippet, shell command and Latex formulas are not treated as restructured text the
indent between these can vary.

Instead of dashes one can use "=" or "_"

> something as light as:
> 
> | [CODE]
> | // some code example
> |

Yes, I really like this notation and will add it.  

> 
> Would be at least as simple to parse and be much easier to compose manually.

For composing documents with reStructured Text macros for your text editor of choice are really
handy.  For example, here's a demo of a Vincent Driessen's VIM plugin dealing with tables  

http://vimeo.com/14300874


> 
> 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.

Very true.

> 
> Is this tool available somewhere ?


You can get it from gitHub:
https://github.com/michael-lehn/DocTool

But please understand, so far I used this tool only for myself.  And extended it
from time to time for my own needs. So it really lacks documentation of itself.
And it also don't know how hard it will be to install on other platforms (I am
using Mac OS X).  I just wrote this short getting started today (but it's really
basic):
http://www.mathematik.uni-ulm.de/~lehn/DocTool/




Michael