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.
So in the following case: # documentation of function f # foo # [bar](http://example.com) function f() f() would be the key in the global dictionary, and the preceding the comments would be converted to markdown format and associated with that key. I'm sure that would cover the majority of the usecases, and lead to prettier, well documented plain text source code. At the same time the machinery you suggested can be added to it for the more complicated cases that need it. On Thursday, 28 August 2014 12:31:19 UTC+2, Steven G. Johnson wrote: > > Another problem with using comments, besides the requirement that Stefan > pointed out of a separate processing pass (as opposed to automatic > availability of metadata at runtime like in Python) is that then the > metadata is not Julia: we lose the flexibility of the metadata being > arbitrary Julia objects, as opposed to just strings. > > My proposal (in the abovementioned issue) is that the metadata be any > Julia object, when then gets converted into output formats by using > writemime methods. For example, if the object has writemime(io, > "text/markdown", x), then you can get output in Markdown format (probably > faciliated by an md"...." constructor). But if at some later point in > time you want to attach SVG documentation, or some future documentation > format, then you can easily do that by defining an appropriate container > object. And since the objects can be queried to find out what MIME > formats they support, you can perform automated translation between > different formats (e.g. conversion of markdown and plain-text docstrings to > HTML or LaTeX output). > > Of course, with comment-based documentation then we could theoretically > embed a little programming language (TeX?) in the comments to achieve the > same thing, but since we already have a perfectly good programming language > (we hope!), this seems silly. It is more likely that a comment-based > documentation implementation would use a fixed format, something we are > then stuck with for all time. >
