Documenting a functor / callable struct


#1

I’m interested in providing a docstring for a functor / callable struct I’m using, but I have to questions about that:

  1. How do you correctly query for the doc string at the REPL? The ?MyFunc (assuming code below) obviously shows the documentation for the struct, so how do you look for the callable method? (Guessing variations of something like ?(::MyFunc) haven’t worked either.)
  2. What’s the (probably related) syntax for making a reference in Documenter.jl’s Markdown?

Potentially related is the fact that I think there must be a bug in the current implementation — on both v0.6 and master, using the following file:

"""
Docs for `MyFunc` struct.
"""
mutable struct MyFunc
    x
end

"""
Docs for calling `f::MyFunc`.
"""
function (f::MyFunc)(x)
    f.x = x
    return f
end

including the file suggests the f symbol is being bound [somewhere] (based on the fact that it’s echoing the last thing in the file to the prompt) and trying to get help on whatever f is seems pretty ambiguous with both an error message and the docstring I was hoping to find.

julia> include("functordoc.jl")
f

help?> f
search: fd for fma fld fft full fld1 find filt fill fft! fdio frexp foldr foldl flush floor float first findn filt! fill! fetch FFTW fldmod findnz findin filter falses finally foreach flipdim

Couldn't find f
Perhaps you meant fd, if, !, %, &, *, +, -, /, :, <, >, I, \, ^, |, ~, ×, ÷, π, ℯ, ∈, ∉, ∋, ∌, ∘, √, ∛, ∩, ∪, ≈, ≉, ≠, ≡, ≢, ≤, ≥, ⊆, ⊇, ⊈, ⊉, ⊊, ⊋, ⊻, ⋅, fft, fld, fma, for, Inf, Ref, eof, != or .%
  Docs for calling f::MyFunc.

If I’m not misinterpreting and/or doing something wrong, I’d be happy to open an issue on Github.


#2

@doc f returns just the Docs for calling f::MyFunc., but I would still argue that this is a bug since f is technically an argument of that function, and could be anything (usually unrelated to the type).

Practically, for types I make callable I just document the type.

Please check that there is no issue and if not, open one.


#3

This is bugged. Somehow the docstring is associated to the Symbol :f.

I think this is related to https://github.com/JuliaLang/julia/issues/20087, but I would advise to open a new issue.


#4

It looks like the same issue.


#5

Then just post the problem there.


#6

Hopefully https://github.com/JuliaLang/julia/pull/25626 should fix it.