I’m very new to Julia, but the only official guidance on Julia docstring conventions I’ve been able to find suggests repeating the function signature in the docstring. This seems kind of redundant and hard to maintain (if you’re changing function signatures semi-frequently), at least compared to pyt…

You’re right that it is a pain to maintain, but it is hard to question the utility of having the function signature displayed as part of the docstring. It tells the reader how to call the function in a non-ambiguous way. To help automate this tedious process, you can use [image] GitH…

Due to the paradigm of multiple dispatch, most functions have multiple call signatures, so documenting the signatures is not redundant.

But the docstring is associated to a specific implementation of a function, right? For example if I had """ add(x, y) adds x and y """ function add(x, y) versus """ add(x::Int, y::Int) adds two integers x and y """ function add(x::Int, y::Int) The call signature in the docstring is sti…

There can be cases where the function is defined with some arguments untyped, but there is still some (more or less) restricted signature that is actually supported in terms of semantic versioning. One example is functions that take any callable object - naively you may want to type that as ::Funct…

Yes, the distinction between a function and its methods is a good portion of this story. A function often has one core meaning but multiple implementations. So you might choose to document how add(x, y) behaves, even if no ::Any, ::Any method exists, because that’s the general behavior new methods…

[image] mlouis9: But the docstring is associated to a specific implementation of a function, right? This can get very subtle, but both a function (a.k.a. a table of methods), and a method (a specific implementation of the function) have a docstring. The function docstring is usually concatena…

Sometimes the implementation contains a lot of cruft that’s not relevant to the caller, while the docstring’s signature can be written in a more user-friendly way that focuses on how the function/method is called, rather than how it’s implemented. Something like this: """ diffetruct([T,] f, x, …

The language server has code actions for adding and update the signatures (see https://github.com/julia-vscode/LanguageServer.jl/pull/1084 and https://github.com/julia-vscode/LanguageServer.jl/pull/1094 ). Here is what this looks like in neovim: [image] If you are using VS Code I think these actio…

A thing that is perhaps worth noting is that traditionally function signatures in julia doc strings are not actually valid julia-code, but rather follow something like the conventions used by linux man pages. https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html In particular …

Yes! Why not have the compiler insert the method signature automatically? Shouldn’t this be extremely easy to implement, even at a syntactic level? When you see code like this: "Some documentation" function func(x::Whatever{T}, default::Real=0.5; keyword::Integer=5)::SomeType where T<:Real # wha…

Why is it Convention to Repeat Function Signatures in Docstrings

General Usage

tecosaur November 5, 2024, 3:21am 9

I do think we could automatically add the attached method’s signature when no signature is present. That seems like a nice QoL change to me, with no clear downside that I’ve seen yet.

4 Likes

Topic		Replies	Views
Seems useful to write a macro that prepends the method signature to the docstring? Internals & Design	3	569	August 9, 2020
Generate doc string with function signature New to Julia documentation	6	1647	April 30, 2019
[ANN] Small VS Code extension to help creating docstrings VS Code	9	387	November 10, 2025
Some thoughts on improving basic function documentation General Usage documentation	51	2361	October 21, 2024
Duplicated function documentation General Usage	2	307	July 7, 2022

Why is it Convention to Repeat Function Signatures in Docstrings

Related topics