Docstring for call / functor syntax

[thofma]

Documenter cannot handle the new call syntax.

doc"""
dasd
"""julia
(::Foo)(::Int) = 1

In the REPL one can access the docstring as follows:

help?> (::Foo)(::Int)
  dasd

When I include it using

```@docs
(::Foo)(::Int)
```

I get:

ERROR: ErrorException("`binding` cannot understand expression `::Foo`.")

expression '(::Foo)(::Int)' in module 'Bla'

[natschil]

Is there any way to get around this for now?
I have a type that is parametrized by an integer, and this prevents me from documenting the constructors...

[mortenpi]

Just a few notes for future reference here: there is actually an upstream problem here too. The docstring storage does not distinguish between the call syntax methods and outer constructor methods:

module Foo1
    "Foo.Bar"
    struct Bar
        x :: Int
    end
    "constructor"
    Bar(::String) = Bar(0)
    "call syntax"
    (::Bar)(::Array) = 1
end

julia> Docs.meta(Foo1)[Docs.Binding(Foo1,:Bar)].docs
IdDict{Any,Any} with 3 entries:
  Union{}       => DocStr(svec("Foo.Bar"), nothing, Dict{Symbol,Any}(:typesig=>Union{},:module=>Main.Foo1,:linenumb…
  Tuple{String} => DocStr(svec("constructor"), nothing, Dict{Symbol,Any}(:typesig=>Tuple{String},:module=>Main.Foo1…
  Tuple{Array}  => DocStr(svec("call syntax"), nothing, Dict{Symbol,Any}(:typesig=>Tuple{Array},:module=>Main.Foo1,…

In fact, you can see that it gets overwritten:

module Foo2
    "Foo.Bar"
    struct Bar
        x :: Int
    end
    "constructor"
    Bar(::String) = Bar(0)
    "call syntax"
    (::Bar)(::String) = 1
end

┌ Warning: Replacing docs for `Main.Foo2.Bar :: Tuple{String}` in module `Main.Foo2`
└ @ Base.Docs docs/Docs.jl:223

julia> Docs.meta(Foo2)[Docs.Binding(Foo2,:Bar)].docs
IdDict{Any,Any} with 2 entries:
  Union{}       => DocStr(svec("Foo.Bar"), nothing, Dict{Symbol,Any}(:typesig=>Union{},:module=>Main.Foo2,:linenumb…
  Tuple{String} => DocStr(svec("call syntax"), nothing, Dict{Symbol,Any}(:typesig=>Tuple{String},:module=>Main.Foo2…

[MilesCranmer]

What's the status of this? I don't know how Docs.jl works internally, but your example seems to work if I just call @doc on Julia 1.9.0-rc2

julia> module Foo1
           "Foo.Bar"
           struct Bar
               x :: Int
           end
           
           "constructor"
           Bar(::String) = Bar(0)
           
           "call syntax"
           (::Bar)(::Array) = 1
       end
Main.Foo1

julia> using .Foo1

julia> @doc Foo1.Bar(::String)  # constructor

julia> @doc (::Foo1.Bar)(::Array)  # call syntax

so is there a reason this doesn't also work with Documenter.jl? (i.e., why does it matter if the docs get overwritten?)

[mortenpi]

No, it still gets overwritten in 1.9 as far as I can tell:

julia> @doc Foo2.Bar(::String)
  call syntax

julia> @doc (::Foo2.Bar)(::Array)
  Foo.Bar

  call syntax

[jakobjpeters]

Here is a workaround that I'm using, just in case it's useful to anyone else.

Julia

module M

struct Real end
struct Fake end

"""Real"""
function Real(x) end

"""(::Real)"""
function Real(::Fake) end
function (::Real) end

end # module

Markdown

``@docs
M.Real
``

HTML

┌───────────────┐
│ M.Real — Type │
├───────────────┤
│ Real          │
│ (::Real)      │
└───────────────┘