Simplify function signature insertion in docsystem ?

[Carreau]

Hi,

I've been following docsystem from far away and got a chance to try master in the last few days.
I must say that the new doc system is great, I have questions & proposals I search a bit if thiswas proposed but did not find reference to it anywhere.

It seem to me that when writing doc for a function you have to re-include the signature manually.
Out of experience in javascript, and Python a bit too, this get cumbersome and often quickly out of sync.

Did you thought about inserting the function/methods signature Automatically ? I guess yes, but there are edge-cases where you might not want the function signature. Would it be possible to have a placeholder like {{signatures}} that would be replace by the signature(s) of the function(s) or representation of object(s) the doc is attached to ? That would make docs easier to write.

Typical example from #12703

"""
    checkout(pkg, [branch="master"])

Checkout the `Pkg.dir(pkg)` repo to the branch `branch`. Defaults to checking out the
"master" branch. To go back to using the newest compatible released version, use
`Pkg.free(pkg)`.
"""
 checkout(pkg::AbstractString, branch::AbstractString="master"; merge::Bool=true, pull::Bool=true) =
     cd(Entry.checkout,pkg,branch,merge,pull)

(note that doc is imprecise and miss merge and pull arguments)

would become

"""
    {{signature}}

Checkout the `Pkg.dir(pkg)` repo to the branch `branch`. Defaults to checking out the
"master" branch. To go back to using the newest compatible released version, use
`Pkg.free(pkg)`.
"""
 checkout(pkg::AbstractString, branch::AbstractString="master"; merge::Bool=true, pull::Bool=true) =
     cd(Entry.checkout,pkg,branch,merge,pull)

[hayd]

See also #9838.

Unfortunately I'm not sure it (yet?) makes sense attaching to a specific method, for one thing there's syntax to attach it to the function (which doesn't have a unique signature). The current convention is you to write the docstring as general as possible and write a faux-signature to match... but I agree that's far from ideal.

cc @MichaelHatherly I suspect this came up in Docile!

It would be nice to get that [] syntax from methods, see #5971.

[MichaelHatherly]

but I agree that's far from ideal.

Also agree, having docs going out of sync isn't great. I have got a basic prototype of the placeholder idea going in https://github.com/MichaelHatherly/Docile.jl/tree/rewrite where signatures are automatically captured in a variable doc!sig (the name is definitely not set in stone) which can then be interpolated into a docstring like so:

"""
    $doc!sig

...
"""
f(x) = ...

The trouble I've run into is how much a signature should be simplified, or whether it should be simplified at all. Other than that I've found this approach to work quite well so far.

[Carreau]

Well with more detailed info on signature, and which docs attached to which signature, (and more time) I would love in Jupyter notebook to turn the completer into something that would show you the signature and the relevant docs for the given selected signature. Something like that:
.

That just a draft, but I can see the use of it.

Thanks for the link about various issues, I'll try to investigate.

[cstjean]

I like $doc!sig in principle, but it still adds three mostly-empty lines of vertical space to every docstring, and it's going to be there 3/4 of the time.

Alternate proposal: "Add the signature" is a better default than "Don't add it". The signature could be automatically added to the docstring for method definitions (like checkout), but not for generic function definitions like function convert end and docstrings added via @doc. Eg.

""" Returns the first element of a collection """ # signature added
first(x) = x[1]


""" 
    abs(x)

The absolute value of x.
"""
function abs end



@doc """ 
... Signature not added here
""" foo(x) = ...

[MichaelHatherly]

I should have probably linked to DocStringExtensions.jl here when I initially registered it, which implements the $doc!sig idea (but with the name $SIGNATURES instead). The concern about repetition is definitely worth sorting out, possibly with the proposed docstring "templates" in JuliaDocs/DocStringExtensions.jl#22.