[ANN] AutomaticDocstrings.jl

Package Announcements
1

AutomaticDocstrings.jl:

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.
Customization options are detailed in the readme.

2

Perfect timing on this! I have been procrastinating adding good doc strings to my packages for far too long and was planning to finally buckle down next week :grin:

3

Thanks for this package! I have a slightly different use case but can probably reuse some of your functions. Curious to hear your thoughts though. I’m generating a wrapper of a C API, and want to generate docstrings with information from the Doxygen documentation, which is stored in a XML file.

So rather than adding @autodoc I just want to run it for entire files generated by Clang.jl, and do the equivalent of a Dict lookup for building the docstring.

A first version of this was already done a few years ago but if I can make it simpler and more flexible that’d be great.

4

I found using a parser (CSTParser.jl and the native julia parser in this case) is much easier than writing manual regexps. In your case, that would correspond to an XML parser that somehow understands the doxygen format. If such a parser is available it would possibly make your job easier.

The CSTParser function that determines if an expression defines a function might also be helpful to you, see my use of it here.

5

Haven’t tried it yet, but it looks like clang-doc is a promising tool for doing this kinda job.