abbreviated syntax for docstrings

[stevengj]

Rather than @doc docstring -> foo(x) = ..., we have discussed allowing docstring foo(x) = ... in #8791. i.e. treat any literal string (including string macros!) immediately preceding a function declaration (either one-line or function foo...) as shorthand for @doc.

[prcastro]

Is the -> gonna be dropped sometime? I really would like to be able to write:

@doc """
... flowing rivers of technical poetry ...
"""
function foo() ...

[stevengj]

@brk00, we're hoping to drop the @doc too in most cases: the proposal was that any literal string immediately before a function (separated only by whitespace) will be parsed as documentation.

[tknopp]

+1

[prcastro]

Is this feature expected to arrive for 0.4?

[StefanKarpinski]

I made a comment over here that is very relevant to this issue. The situation can be summarized as:

1. we want to parse bare docstrings as part of Julia's syntax
2. we want to render and interpret docstring content as Markdown text
3. it is unacceptable to make the Julia parser depend on a Markdown parser

Therefore Markdown parsing must happen when docstring data is rendered as Markdown, rather than when docstrings are parsed as part of Julia's syntax.

Until this issue is resolved – i.e. until Markdown parsing is deferred to when the docstring data is used, rather than happening eagerly when the docstring is parsed – docstrings are going to remain "stuck in limbo as a clever macro hack rather than a first class language feature".