I really like Steven Johnson's proposal. I've often imagined a similar system, although I never considered using writemime as a generalization mechanism. It seems like consensus is slowly building around embedding compiler specific metadata directly into the AST with a metadata node. It would seem natural to use this for documentation as well. Comments would similarly be embedded into the AST instead of being skipped. That way documentation lives with a julia expression, and since the AST can could contain arbitrary Julia values (if we have a pure Julia frontend at some point) we get the full generality Steven outlined above. Since documentation is now first class, the reflection / metaprogramming mechanisms we use in Julia could be extended to generating documentation. Documentation, would also have access to the literal values of the runtime system instead of just symbolic values. Documentation is dynamic and introspective, it has full access to the julia source code and parsed AST it references. It would certainly be a more powerful system than anything out there I am aware of.
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. > > 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. >> >
