Documenter: callable objects

General Usage
1

Is it possible to document a callable object “call” definition?
Documenter complains about documentation not found. This is the code location: (MeshCore.jl/increl.jl at 80229d26e7a7e4a821b04df2815604101e595375 · PetrKryslUCSD/MeshCore.jl · GitHub).

2

I’m wondering about this, too. Maybe the easiest example is the following:

"B doc"
struct B end

"B callable doc"
(::B)(x) = 1

With docs/src/index.md of the form

```@docs
B
(::B)(::Any)
```

the first docstring works, but Documenter.jl complains about the second:

Error: unable to get the binding for '(::B)(::Any)' in `@docs` block in src/index.md:1-4 from expression ':((::B)(::Any))' in module Main

How does one do this correctly?

BTW, if one only says

```@docs
B
```

then Documenter.jl does not complain that the second docstring is not included in the documentation.

(I’m using Documenter.jl v1.17.)

3

The callable should be documented as part of the struct docstring. I would generally advise against splitting up docstrings too much: document functions (or structs), not methods.

4

Julia allows to attach docstrings to callable methods like (::B)(x) above. Moreover,

help> B()(1)

only returns the docstring for the callable method, not for B itself. It’s of course debatable whether attaching a docstring to a callable method is a good idea. However, given that this feature exists in Julia, I think it would make sense for Documenter.jl to support it and leave the decision to the user.