James Wrigley (Jul 02 2022 at 12:56): 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.
Michael Fiano (Jul 02 2022 at 12:57):I think JuliaFormatter.jl can be told to do that IIRC
James Wrigley (Jul 02 2022 at 13:00):Ah hah, thanks.
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?
James Wrigley (Jul 02 2022 at 13:01):Yeah I see there's format_docstrings.
Fredrik Ekre (Jul 02 2022 at 13:02):You can checkout https://github.com/JuliaDocs/DocStringExtensions.jl
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.
Michael Fiano (Jul 02 2022 at 13:05):So hopefully it doesn't do that
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.
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:
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: Oct 02 2023 at 04:34 UTC