I have some level of eye-bleed from this and several other suggestions, too. The look of comments is part of the language design, and they are (IMO) unobtrusive yet visually indistinct -- and (for the single-line ones, at least) highly unsurprising and conventional. All of which I think is good. I'd *very much* prefer a solution that simply used the last comment before a method as the documentation for it, and having the convention of using Markdown in them, as Stefan argues.
There's talk about using Julia instead of some other language for more complex comment stuff. I guess that depend on what you want to use them for (or if you really want general metadata, rather than documentation). For marking up documentation text, I think a markup language is a good choice. For documentation comments, I think comments are a good choice ;-) However, if one wants more programmability, would it be possible to treat comments as a special form of string literals in themselves (like docstrings), using the existing syntax? I'm assuming they'd just be eliminated from the compiled code, but would be available in the AST. Then one could use the existing Julia syntax for substituting values into the documentation, like: # This is a comment. 1 + 2 = $(1 + 2) I'm not sure I'd have any use for the extra programmability, and it doesn't mean that the comment/string could end up as anything other than a string. (There are, I guess, lots of suggestions for handling the latter issue already.) But, yeah, I wholeheartedly agree with Stefan in that we "don't need flexible documentation – we need one simple documentation system that works."
