Sorry for the mistake,

2016-09-16 15:51 GMT+02:00 Damien Pollet <>:

> On 16 September 2016 at 15:35, Thierry Goubier <>
> wrote:
>> Could we have a Pillar-way of organizing comments so that, based on
>> sections, one could automatically find, from a book-like comment of the
>> package or the class, which section applies to a given method?
> I guess it's like any cross-referencing or indexing system… I'm guessing a
> purely automatic system would find irrelevant matches and miss related
> stuff, so it would need some human-added hints. But no one can reasonably
> go through the cross-product of docs and code, adding hints, so that would
> need to be crowdsourced and aggregated, a bit like the QA critiques.

If one could reference the package code (class / method) as a reference
inside the Pillar comment, would that work? I'm a bit wary of an
'automatic' approach, but I'd find great to go in a fluid way from text to
code and back.

For those who remember, my idea would be like referencing chapters and
sections of the LaTeX generation of smalltalk source code... If you
reference {\ref aClass:aProtocol:aMethod} then you get a live two-way link
between the comment and the code in the browser.

> I'll leave this link to the Django docs: https://docs.
> I recently watched a talk from I think the Django lead who was explaining
> the different kinds of docs (tutorials, howtos, topic guides, and
> reference). Package/class/method comments would be reference doc, but would
> need to cross-ref with any other docs too…

I'd make it simple: start with a book-like document cross-referenced with
the live code, as the preferred documentation for a package.


> --
> Damien Pollet
> type less, do more [ | ]

Reply via email to