AutomaticDocstrings
This small package automatically generates docstring stubs for you to fill in.
Install using import Pkg; Pkg.add("AutomaticDocstrings")
Usage
Place the macro call @autodoc
above the function or struct definition that you want to generate a docstring for:
using AutomaticDocstrings
@autodoc
function f(x::A, b=5; c=LinRange(1,2,10)) where A
5
end
When you execute the macro, e.g. by ctrl-enter in Juno, the macro is replaced by a docstring
"""
f(x::A, b=5; c=LinRange(1,2,10))
DOCSTRING
# Arguments:
- `x`: DESCRIPTION
- `b`: DESCRIPTION
- `c`: DESCRIPTION
"""
function f(x::A, b=5; c=LinRange(1,2,10)) where A
5
end
Before modifying your file, a backup is saved.
[ Info: Saved a backup to /tmp/jl_VQvgbW/backup
If you don't like the docstring or if something went wrong, ctrl-z (undo) works fine as well.
Limitations
- If a file with multiple
@autodoc
areinclude
ed, then only the first will be executed and then an error is thrown. Instead ofinclude(file)
callautodoc(file)
. - Make sure the file is saved before you try to generate any docstrings.
Options
You may modify the AutomaticDocstrings.options::Dict
to change some default values:
:min_args = 3
: Minimum number of arguments to print the argument list of function:args_header = "# Arguments:"
: Printed above the argument list of function:kwargs_header = nothing
: Printed above the keyword argument list of function:struct_fields_header = "# Fields:"
: Printed above the fields list of a struct:arg_types_in_desc = false
: Include the argument types in the description:defaults_in_desc = false
: Include the default values in the description:arg_types_in_header = false
: Include the argument types in the function header:defaults_in_header = false
: Include the default values in the function header
You can always call restore_defaults()
to restore the default options.