[cfe-dev] [PATCH] LibTooling docs

[Manuel Klimek]

So, I've pondered this a bit over the weekend...

There are multiple things around this on my mind:
1. documentation is more than a code walkthrough - the documentation
must be able to be structured differently from the code, whose
structuring is imposed by a compiler (that's mainly as a direct answer
to Sean's proposal)
2. I like the idea of having testable code-snippets included in the
docs; the biggest problem is that I don't think it makes sense to have
a special solution for the docs I'm writing; we should take this
proposal to llvm-dev and discuss it with the people who're working on
doc standards for llvm already, like the proposed move towards a
different markup system altogether; the biggest problem here is people
willing to maintain it and convert existing docs - some of the ideas
around documentation have apparently been "in the works" for many
months now, but have always been too low prio
3. I also agree to some point with James' comments: documentation is a
people problem, which we cannot solve with technical means - and
having auto-checked syntax in documentation might disincentivice
engineers (like myself) from checking the docs; that said, as long as
the writers of the documentation think a system can help them, I think
we can use it - it's not like this will magically solve the problem of
too little documentation, but making documentation easier to maintain
is definitely something I'm interested in.

To me, my main concern seems to be (1). I don't want a special
solution for the docs around tooling.

David, why not bring up the whole question about automatically checked
documentation, and the documentation strategy in general (and your
ideas, obviously) up on llvm-dev?

Cheers,
/Manuel

On Mon, Apr 23, 2012 at 3:11 AM, Sean Silva <silvas at purdue.edu> wrote:
> Fwiw, when it comes to a kind of "code walkthrough", I think that something
> like this <http://documentcloud.github.com/underscore/docs/underscore.html>
> could be a good model. The docs are generated from comments *in the code*,
> so that they are unlikely to go out of date. The program that does that
> transformation is called Docco and it is very few lines of code (see here
> <http://jashkenas.github.com/docco/>). There are ports of this tool for many
> languages (they are listed on that page) and they are all equally small.
>
> --Sean Silva
>
> On Sun, Apr 22, 2012 at 5:37 AM, David Röthlisberger <david at rothlis.net>
> wrote:
>>
>> On 21 Apr 2012, at 18:42, David Blaikie wrote:
>> >> On Sat, 21 Apr 2012 14:28:03 +0100
>> >> David Röthlisberger <david at rothlis.net> wrote:
>> >> I am a big fan of *testable* documentation.
>> >
>> > Manuel - sorry if this takes a bit of a tangent from your review... I
>> > don't think any of this is likely to be sufficiently
>> > relevant/important to require you to respond before committing your
>> > documentation.
>>
>>
>> Absolutely -- In fact I'm a bit sorry for distracting from the review of
>> the documentation *content* by submitting my wacky ideas. Let's get Manuel's
>> static html --which is really valuable work-- committed before carrying this
>> discussion any further.
>>
>> --David Röthlisberger.
>>
>>
>> _______________________________________________
>> cfe-dev mailing list
>> cfe-dev at cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>
>
>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>