# \[ANN\] Small VS Code extension to help creating docstrings

**URL:** <https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765>\
**Category:** VS Code\
**Created:** [November 9, 2025, 7:46pm UTC](https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765 "2025-11-09T19:46:53Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![Ronis\_BR](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ronis_br/32/50999_2.png) [@Ronis\_BR](https://discourse.julialang.org/u/Ronis_BR)\
**Post date:** [November 9, 2025, 7:46pm UTC](https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765/1 "2025-11-09T19:46:53Z")

</div>

Hi!

I am moving from Neovim to VS Code for my development workflow. In Neovim, I had a lua function to extract information from the function declaration and help me creating docstrings. Hence, I released a small extension to VS Code to do the same:

> **[Julia DocStrings - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ronisbr.julia-docstrings)**
>
> Extension for Visual Studio Code - Create docstrings for objects in Julia language.

Basically, you select the text with the function declaration, like:

```julia
function my_function(x::Int, y::Int, z::Int = 3; verbose::Bool = false)

```

and call a command to insert the following snippet:

```julia
"""
    my_function(x::Int, y::Int, z::Int = 3; kwargs...) -> <Return type>

<Description of the function>

# Arguments

- `x::Int`: <Argument description>
- `y::Int`: <Argument description>
- `z::Int`: <Argument description>
    ( **Default** : `3`)
# Keywords

- `verbose::Bool`: <Keyword description>
    ( **Default** : `false`)
"""

```

Where everything between `<>` are placeholders that you can navigate using TAB. It fits for my development strategy by writing the most annoying part of the documentation following the template I like. Currently, the extension supports only macros and functions but I am planning to support structures as well.

---

<div class="post-metadata">

**Author:** ![ForceBru](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/forcebru/32/21389_2.png) [@ForceBru](https://discourse.julialang.org/u/ForceBru)\
**Post date:** [November 9, 2025, 9:40pm UTC](https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765/2 "2025-11-09T21:40:30Z")

</div>

Why oh why do we have to _manually_ repeat method signatures in docstrings… [https://discourse.julialang.org/t/why-is-it-convention-to-repeat-function-signatures-in-docstrings/](https://discourse.julialang.org/t/why-is-it-convention-to-repeat-function-signatures-in-docstrings/). Seems like the compiler is in _perfect_ position to automatically prepend the correct signature to each docstring

---

<div class="post-metadata">

**Author:** ![gdalle](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gdalle/32/27854_2.png) [@gdalle](https://discourse.julialang.org/u/gdalle)\
**Post date:** [November 9, 2025, 10:34pm UTC](https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765/3 "2025-11-09T22:34:27Z")

</div>

Looks very cool!  
DocStringExtensions.jl does a bit of that parsing but I am not a fan of some design choices / limitations there (like not showing default values for keyword arguments if memory serves) so this extension might be useful

---

<div class="post-metadata">

**Author:** ![Ronis\_BR](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ronis_br/32/50999_2.png) [@Ronis\_BR](https://discourse.julialang.org/u/Ronis_BR)\
**Post date:** [November 10, 2025, 12:10am UTC](https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765/4 "2025-11-10T00:10:37Z")

</div>

> [@ForceBru](#):
>
> Why oh why do we have to _manually_ repeat method signatures in docstrings…

Well, I have no idea 😃 I am just used to this pattern when documenting all my functions.

---

<div class="post-metadata">

**Author:** ![tecosaur](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tecosaur/32/23206_2.png) [@tecosaur](https://discourse.julialang.org/u/tecosaur)\
**Post date:** [November 10, 2025, 11:19am UTC](https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765/5 "2025-11-10T11:19:26Z")

</div>

> [@Ronis\_BR](#):
>
> Well, I have no idea 😃 I am just used to this pattern when documenting all my functions.

If there isn’t already an issue in the Julia repo about doing this, maybe I should make one…

I can’t see any downside to automatically prepending a signature to docstrings that don’t start with a code block.

---

<div class="post-metadata">

**Author:** ![Ronis\_BR](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ronis_br/32/50999_2.png) [@Ronis\_BR](https://discourse.julialang.org/u/Ronis_BR)\
**Post date:** [November 10, 2025, 11:49am UTC](https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765/6 "2025-11-10T11:49:57Z")

</div>

> [@tecosaur](#):
>
> I can’t see any downside to automatically prepending a signature to docstrings that don’t start with a code block.

This will be awesome! Because 95% of time, I really do not need this kind of configurability. Can the system take all the information, including the variable’s name, or only the variable’s type?

---

<div class="post-metadata">

**Author:** ![pfitzseb](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/pfitzseb/32/45566_2.png) [@pfitzseb](https://discourse.julialang.org/u/pfitzseb)\
**Post date:** [November 10, 2025, 11:55am UTC](https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765/7 "2025-11-10T11:55:13Z")

</div>

Docstrings are lowered to macro calls and should therefore have access to all required info to reproduce the function signature.

Btw, this functionality is also available via LanguageServer.jl, just in a much worse form:

AFAICT it’s not possible to reproduce the nice snippet/tab stuff with `TextDocumentEdit`s directly ☹

---

<div class="post-metadata">

**Author:** ![Ronis\_BR](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ronis_br/32/50999_2.png) [@Ronis\_BR](https://discourse.julialang.org/u/Ronis_BR)\
**Post date:** [November 10, 2025, 1:43pm UTC](https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765/8 "2025-11-10T13:43:50Z")

</div>

> [@pfitzseb](#):
>
> AFAICT it’s not possible to reproduce the nice snippet/tab stuff with `TextDocumentEdit`s directly ☹

I see! The snippet/tab is not the most useful thing in my workflow, it is the argument / keyword listing with their default values. It is very annoying to add this information following the template in Blue style / Julia official docs.

---

<div class="post-metadata">

**Author:** ![tecosaur](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tecosaur/32/23206_2.png) [@tecosaur](https://discourse.julialang.org/u/tecosaur)\
**Post date:** [November 10, 2025, 1:44pm UTC](https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765/9 "2025-11-10T13:44:28Z")

</div>

> [@tecosaur](#):
>
> an issue in the Julia repo about doing this, maybe I should make one

…or maybe a PR? 🤔

---

<div class="post-metadata">

**Author:** ![ForceBru](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/forcebru/32/21389_2.png) [@ForceBru](https://discourse.julialang.org/u/ForceBru)\
**Post date:** [November 10, 2025, 1:46pm UTC](https://discourse.julialang.org/t/ann-small-vs-code-extension-to-help-creating-docstrings/133765/10 "2025-11-10T13:46:05Z")

</div>

> [@tecosaur](#):
>
> I can’t see any downside to automatically prepending a signature to docstrings that don’t start with a code block.

Yes! Some ideas:

1. As you say, if a doctoring begins with a code block, leave it alone.
2. If a function/method has no docstring, don’t add a docstring. Otherwise the documentation for functions with multiple methods will be extremely long, listing every single method.
3. If the function is defined as literally `function func_name end` (no function body), insert its docstring (call it “general docstring”) into other auto-generated docstrings as follows: `"$signature\n$general_docstring\n$specific_docstring"`. The general docstring is supposed to describe the overall purpose of the function `ModuleName.function_name`.
4. The function signature should be copied verbatim from the method it belongs to, including keyword arguments, types (possibly auto-minified) and default arguments.

Example “specific docstring”:

```julia
# ===== In Distributions.jl =====
"""
Fit a probability distribution via maximum likelihood.
"""
function fit_mle end

# ===== Elsewhere =====
"""
Fits the Student's t distribution using the EM algorithm.
"""
function Distributions.fit_mle(d::TDist, xs::AbstractVector{<:Real})
    # code here
end

```

Example output:

```julia-auto
help?> fit_mle(TDist(1.5), [1,2,3])
   fit_mle(d::TDist, xs::AbstractVector{<:Real})

   Fit a probability distribution via maximum likelihood.
   Fits the Student's t distribution using the EM algorithm.

```

But perhaps such docstrings will be too cluttered. After all, one could just ask for `?fit_mle` and get docstrings for _all_ methods, including the one without the body.