Oh, man. I'm sorry but that makes my eyes bleed. Why can't we just associate the literal content of the comments with the appropriate function objects and other bindings and then leave the interpretation of those blocks of text to the presentation layer? I don't see much to be gained by making this completely programmable.
On Thu, Aug 28, 2014 at 4:20 PM, Steven G. Johnson <stevenj....@gmail.com> 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""" ... """. >
