Format docstrings

[stelmo]

Is there a way to generate formatted docstrings using DocStringExtensions.jl? For example, in a package we are currently developing our docstrings are defined like this:

"""
    add_reactions(
        m::CoreModel,
        s::V1,
        b::V2,
        c::AbstractFloat,
        xl::AbstractFloat,
        xu::AbstractFloat;
        check_consistency = false,
    ) where {V1<:VecType,V2<:VecType}

Add reaction(s) to a `CoreModel` model `m`.
"""

but we would like to make use of DocStringExtentions.jl like this:

"""
    $(TYPEDSIGNATURES)

Add reaction(s) to a `CoreModel` model `m`.
"""

However, the generated docstrings look like this:

help?> add_reactions
search: add_reactions add_reactions! @add_reactions! with_added_reactions add_reaction!

  add_reactions(m::CoreModel, s::V1<:AbstractVector{Float64}, b::V2<:AbstractVector{Float64}, c::AbstractFloat, xl::AbstractFloat, xu::AbstractFloat; check_consistency) -> Union{CoreModel, Tuple{CoreModel, Vector{Int64}, Vector{Int64}}}
  
  Add reaction(s) to a CoreModel model m.

which makes it difficult to read. It would be great if we could format them somehow. Is there functionality for this?

[exaexa]

(Autoformatting can be done by JuliaFormatter's functions, e.g. https://domluna.github.io/JuliaFormatter.jl/stable/api/#JuliaFormatter.format_text-Tuple{AbstractString} )

[mortenpi]

I think this would be great. We could probably check for the length of the single line docstring and then make it multiline if it's longer than some number of characters?

[exaexa]

Yes, just breaking the thing to lines would in my opinion solve the majority of the problematic the use-cases.

Instead of

f(a, b, c, d)

write, in case line width can't fit length of the signature + indent,

f(
  a,
  b,
  c,
  d,
)

There might be cases where this still breaks, such as when people have long typenames or very long default values (e.g. functions with begin/end), but these would really require JuliaFormatter to be taken care of properly. Possible example of what not to care about:

fn(
  test::LongNamedAbstractThingInterface{AbstractLongNamedThingInterfaceProbablyContentIdontKnow},
  test2 = (p1,p2,p3) -> begin do_this(p1); also_now_do_that(p2); and_finally_do_something_more(p3) end,
)

[stelmo]

I started working on this here. Basically, I modified printmethod to calculate the length of the method signatures and then break them into multiline format if longer than some threshold (no JuliaFormatter involvement). I will test it out on my packages to see if it looks ugly and then make a PR if not.