AutomaticDocstrings.jl

Automatically generated docstring stubs
Author baggepinnen
Popularity
12 Stars
Updated Last
6 Months Ago
Started In
May 2019

AutomaticDocstrings

Build Status PkgEval codecov

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 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.
  • 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.

Required Packages

Used By Packages

No packages found.