For that, I think it would suffice to have a programmatic way of manipulating the associated data. The comments desugar to doing that, but you can also just do it directly.
On Thu, Aug 28, 2014 at 5:05 PM, John Myles White <[email protected]> wrote: > As we're starting to get better ideas for a documentation system, two > questions I have are how we do two things: > > (1) Handle documentation of generic functions and their specialized > methods without requiring documentation of all specialized methods. > > (2) Handle documentation of functions that being generated by macros. > > Both of these come up as soon as you start writing documentation for > things like getindex. We definitely don't want to require writing a comment > block for every method of getindex. > > -- John > > On Aug 28, 2014, at 1:20 PM, Steven G. Johnson <[email protected]> > wrote: > > On Thursday, August 28, 2014 9:16:27 AM UTC-4, Job van der Zwan wrote: >> >> Could we not have both, in a way? A sensible convention for comment-based >> documentation using markdown, which I expect covers the vast majority of >> usecases (being human-readable plaintext that converts to rich text). >> During compilation that documentation is converted and added to the global >> dictionary of metadata you propose. >> > > I was thinking more along the lines of: > > doc md""" ... markdown docs for specific method foo(...) ... """ > function foo(...) > ... > end > > doc md""" ... markdown docs for foo Function general ... """ foo > > which would require some parser support (though it should be easy to > implement), but is much more flexible than embedding things in comments. > e.g. you can use arbitrary Julia code to evaluate/generate the > documentation object. It also keeps comments "pure" ... comments should > not be part of the language or have any format that Julia cares about. > > You could also extend it to add other metadata with keywords: doc > section="Foo Functions" author="SGJ" md""" ... """. > > >
