New doc syntax

[MikeInnes]

I'm sure this implementation is far from acceptable (aesthetically and as far as the tests are concerned) but hopefully the core idea is sound. I've used the new syntax for the include doc string for illustration, and as you can easily verify from Base.DocBootstrap.docs the plain docstrings we already have are successfully stored, even before the doc system itself is in place (although we don't process these just yet).

(@Keno @ViralBShah apologies that this is four hours late)

[MichaelHatherly]

Cool! Just giving this a try now. Some results:

At the REPL triplequoted strings work fine for methods:

julia> """f"""
       f() = ()
f (generic function with 1 method)

julia> Main.META
ObjectIdDict with 2 entries:
  #= circular reference =# => Base.Markdown.MD(Any[Base.Markdown.Paragraph(Any["Documen…
  f                        => Base.Docs.FuncDoc([f() at none:2],Dict{Method,Any}(f() at…

Single quotes don't yet, they probably should:

julia> "g"
       g() = ()
ERROR: unsupported or misplaced expression single_quoted_string

I've not had any luck getting a source file documented yet. This gist contains some test cases that should probably be supported. Where should the docs end up? Base.DocBootstrap.docs only has some stored from Base.Markdown and Base, Testcases.META is undefined. Perhaps I'm just missing something quite basic?

[MichaelHatherly]

Switching all the docstrings in the gist to @doc syntax shows up a few problems we have currently:

The syntax

@doc """F""" ->
function F end

gives a type Symbol has no field args error, presumably because that syntax is quite new. Fixed in #11837.

Bitstype

@doc """B""" ->
bitstype 8 B

is being stored as nothing in Testcases.META. Fixed in #11837

The inner constructor

    @doc """C_1""" ->
    C(x) = new()

produces

MethodError: `doc!` has no method matching doc!(::Type{Testcases.C}, ::Method, ::Base.Markdown.MD, ::Expr)

I can open separate issues for each of these, but perhaps it's best to just put the fixes in here and now?

[prcastro]

👍 thanks for doing this

[MikeInnes]

Yeah so the doc macro is a little out of date for some of the newer 0.4 features, I think there are separate issues open for that.

I think the module thing isn't working because technically you're no longer at the top level inside a module. So I just need to patch the part that parses modules too.

[ScottPJones]

👍 🎉

[ViralBShah]

👍