Sorry for the mistake, 2016-09-16 15:51 GMT+02:00 Damien Pollet <[email protected]>:
> On 16 September 2016 at 15:35, Thierry Goubier <[email protected]> > 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. > djangoproject.com/en/1.10/ > 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. Thierry > > > -- > Damien Pollet > type less, do more [ | ] http://people.untyped.org/damien.pollet >
