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

[Matthieu Monrocq]

On Sat, Aug 18, 2012 at 5:36 PM, Michael Lehn <michael.lehn at uni-ulm.de>wrote:

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

Do not worry, I do understand it is a work in progress.

I already have clang working correctly on two environments (Ubuntu server
at home and Suse 11 at work) so I don't think getting the tool to work on
one or the other would be much of a problem. Not sure I'll have much time
before October to really check it out, but it does seem really handy.

Thanks for the links.

-- Matthieu
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120819/a17ed5da/attachment.html>