# \[ANN\] AutomaticDocstrings.jl

**URL:** <https://discourse.julialang.org/t/ann-automaticdocstrings-jl/24675>\
**Category:** Package Announcements\
**Tags:** documentation\
**Created:** [May 28, 2019, 6:45am UTC](https://discourse.julialang.org/t/ann-automaticdocstrings-jl/24675 "2019-05-28T06:45:35Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![baggepinnen](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/baggepinnen/32/693_2.png) [@baggepinnen](https://discourse.julialang.org/u/baggepinnen)\
**Post date:** [May 28, 2019, 6:45am UTC](https://discourse.julialang.org/t/ann-automaticdocstrings-jl/24675/1 "2019-05-28T06:45:35Z")

</div>

# [AutomaticDocstrings.jl](https://github.com/baggepinnen/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:

```julia
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

```julia
"""
    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.

```julia-repl
[ 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](https://github.com/baggepinnen/AutomaticDocstrings.jl).

---

<div class="post-metadata">

**Author:** ![kevbonham](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kevbonham/32/216165_2.png) [@kevbonham](https://discourse.julialang.org/u/kevbonham)\
**Post date:** [May 28, 2019, 10:25am UTC](https://discourse.julialang.org/t/ann-automaticdocstrings-jl/24675/2 "2019-05-28T10:25:25Z")

</div>

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 😁

---

<div class="post-metadata">

**Author:** ![visr](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/visr/32/17204_2.png) [@visr](https://discourse.julialang.org/u/visr)\
**Post date:** [June 1, 2019, 9:42pm UTC](https://discourse.julialang.org/t/ann-automaticdocstrings-jl/24675/3 "2019-06-01T21:42:26Z")

</div>

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](https://github.com/JuliaGeo/GDAL.jl/tree/master/gen) was already done a few years ago but if I can make it simpler and more flexible that’d be great.

---

<div class="post-metadata">

**Author:** ![baggepinnen](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/baggepinnen/32/693_2.png) [@baggepinnen](https://discourse.julialang.org/u/baggepinnen)\
**Post date:** [June 2, 2019, 7:29am UTC](https://discourse.julialang.org/t/ann-automaticdocstrings-jl/24675/4 "2019-06-02T07:29:19Z")

</div>

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](https://github.com/baggepinnen/AutomaticDocstrings.jl/blob/baa321934ae1c3eaf6c4819d1884c27b1cdb8169/src/AutomaticDocstrings.jl#L60).

---

<div class="post-metadata">

**Author:** ![Gnimuc](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gnimuc/32/2194_2.png) [@Gnimuc](https://discourse.julialang.org/u/Gnimuc)\
**Post date:** [June 2, 2019, 8:00am UTC](https://discourse.julialang.org/t/ann-automaticdocstrings-jl/24675/5 "2019-06-02T08:00:03Z")

</div>

Haven’t tried it yet, but it looks like [clang-doc](https://clang.llvm.org/extra/clang-doc.html) is a promising tool for doing this kinda job.

[![](https://global.discourse-cdn.com/julialang/original/3X/0/a/0af4e64390903daa39ad0430613447e0546d6ae6.jpeg "2018 LLVM Developers’ Meeting: J. Hockett “clang-doc: an elegant generator for more civilized doc..”") ](https://www.youtube.com/watch?v=bTzvPhKN0YI)