The proper way of documenting constructors

General Usage
,
1

If a type has outer constructors, Julia’s REPL shows all their docstrings joined together with the type’s docstring when asked for help, which is pretty neat:

"Type docstring"
struct A 
    x
end

"Constructor docstring"
A() = A(0)

and then

help?> A

  Type docstring

  ───────────────────────────────────────

  Constructor docstring

But if I make the constructor inner:

"Type docstring"
struct A
    x

    "Constructor docstring"
    A() = new(0)
end

then the help in REPL only shows Type docstring.

It is even worse in Documenter, where only Type docstring is shown for both variants for the doc file like

```@docs
A
```

So, is that the expected behavior or a bug (or the lack of a feature)? What is the recommended way of documenting constructors? Is it possible to make Documenter show all documented constructors like the REPL does? I would prefer to have inner constructors to control the contents of the type.

2 Likes
2

https://github.com/JuliaLang/julia/issues/16730

2 Likes
3

Thanks, that does fix the issue with REPL, unfortunately Documenter still ignores these docstrings.

4

Hello, I know long time has passed, but just to say this doesn’t seem to be a problem any more… by adding @doc in front to the internal constructor’s docstring, I can have both the struct and the constructor documented in both the REPL and the Documenter output, e.g.:

However you still need to manually add the @doc macro, at least until issue #14962 will be solved.

1 Like