[ANN] Small VS Code extension to help creating docstrings

Tooling VS Code
10

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”:

# ===== 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:

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.