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)) where A
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.
- Short-form function definitions with
where
, e.g.,f(a::A) where A
, does not work.
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
:args_header => "Arguments:" # Printed above the argument list
:full_def => true # Include the full function signature, if false, only include function and argument names
You can always call restore_defaults()
to restore the default options.