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.
