Stream: helpdesk (published)

Topic: Documenter.jl auto-generate type signatures


view this post on Zulip James Wrigley (Jul 02 2022 at 12:56):

Is it possible for Documenter.jl to auto-generate type signatures? So that having a docstring like:

"""
This does foo.
"""
foo(bar, baz; quux=10) = 42

Would create documentation like:

    foo(bar, baz; quux=10)

This does foo.

I've googled a bit but couldn't find anything.

view this post on Zulip Michael Fiano (Jul 02 2022 at 12:57):

I think JuliaFormatter.jl can be told to do that IIRC

view this post on Zulip James Wrigley (Jul 02 2022 at 13:00):

Ah hah, thanks.

view this post on Zulip Michael Fiano (Jul 02 2022 at 13:01):

I haven't actually tried it to see what it looks like, but there's one option that looks like it might do what you want?

view this post on Zulip James Wrigley (Jul 02 2022 at 13:01):

Yeah I see there's format_docstrings.

view this post on Zulip Fredrik Ekre (Jul 02 2022 at 13:02):

You can checkout https://github.com/JuliaDocs/DocStringExtensions.jl

view this post on Zulip Michael Fiano (Jul 02 2022 at 13:05):

@James Wrigley From the manual:

Since the function name is given by the signature, there is no need to start the documentation with "The function bar...": go straight to the point. Similarly, if the signature specifies the types of the arguments, mentioning them in the description is redundant.

view this post on Zulip Michael Fiano (Jul 02 2022 at 13:05):

So hopefully it doesn't do that

view this post on Zulip Michael Fiano (Jul 02 2022 at 13:07):

Also:

Only provide an argument list when really necessary.
For simple functions, it is often clearer to mention the role of the arguments directly in the description of the function's purpose.

view this post on Zulip James Wrigley (Jul 02 2022 at 13:07):

Fredrik Ekre said:

You can checkout https://github.com/JuliaDocs/DocStringExtensions.jl

Oooo yes that does look like what I want :eyes:

view this post on Zulip James Wrigley (Jul 02 2022 at 13:08):

Michael Fiano said:

Also:

Only provide an argument list when really necessary.
For simple functions, it is often clearer to mention the role of the arguments directly in the description of the function's purpose.

I think this is referring to an explicit list of arguments in the docstring, not their presence in the type signature?


Last updated: Nov 06 2024 at 04:40 UTC