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