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