We are repeating the discussion in
https://github.com/JuliaLang/julia/issues/3988
My proposal was to have a global dict associating Julia objects with
arbitrary documentation "objects" (though it really doesn't matter much
where you store it). In response to the points in this thread:
* We want both generic documentation for a function in the abstract, as
well as the possibility of documenting specific methods. My proposal
supported this (the former are metadata for the `Function`, the latter are
metadata for the `Method`.
* Although Markdown is nice to have as a default, I think it is
short-sighted to limit ourselves to a single text format. e.g. what if I
want my documentation to contain images? My proposal supports this: the
documentation can be any object, and `writemime` is used to spit out
specific output formats. One possible object would be a `md""" ..... """`
string representing Markdown-formatted text, which would know how to write
itself natively as "text/markdown"` as well as probably other formats.
* A nice syntax could come later (and hopefully sooner); initially we could
just have a macro
@doc foo: function bar(...)
...
end
A start at this could be found
in https://github.com/JuliaLang/julia/pull/5572
