baggepinnen / AutomaticDocstrings.jl

Automatically generated docstring stubs

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 are includeed, then only the first will be executed and then an error is thrown. Instead of include(file) call autodoc(file).
• Make sure the file is saved before you try to generate any docstrings.

VS code snippet

Adding the following snippet to vscode makes it easy to insert an automatically generated docstring, just make sure to save the file before executing the @autodoc macro.

"autodoc": {
	"prefix": "autodoc",
	"body": ["${1:@eval Main using AutomaticDocstrings}$2\n@eval Main @autodoc"],
},

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.