what is the recommended way to document arguments used only for their type for SIGNATURES?

[tpapp]

This is not (yet) a feature request, just asking for advice on using this package.

Sometimes the value of an argument is not directly relevant, as the body uses their type. Eg (contrived MWE)

using DocStringExtensions

"""
$(SIGNATURES)

Generate a tuple of the first `3N` odd numbers.
"""
foo(::Val{N}) where N = ntuple(i -> 2 * i - 1, Val(2 * N))

which renders as

foo(_)

Generate a tuple of the first 3N odd numbers.

What is the recommended approach to deal with this?

(Using TYPEDSIGNATURES just gives a docstring without the signature, but maybe that is a separate issue)

[MichaelHatherly]

What is the recommended approach to deal with this?

I hadn't put any thought into that particular case, so perhaps there isn't a recommended approach yet. Others feel free to chime in if you've needed this kind of thing.

(Using TYPEDSIGNATURES just gives a docstring without the signature, but maybe that is a separate issue)

If that was resolved to print something out would it go some ways to solving the case for you?

[tpapp]

Yes and no. In a lot of cases resolving that would help me. Eg

"""
$(TYPEDSIGNATURES)
"""
foo(x, ::Val{N}) where N= nothing

does precisely what I want, but I could imagine typing x but not wanting to print that type.

I would recommend that for SIGNATURES, missing argument names (eg _) just print their type if it is different from Any. But that may not work for everyone and it could be that we need a new abbrev.

Incidentally, maybe we could have customizable abbrevs? Eg Signatures(; kwargs...).

[MichaelHatherly]

I would recommend that for SIGNATURES, missing argument names (eg _) just print their type if it is different from Any. But that may not work for everyone and it could be that we need a new abbrev.

Agreed, that seems like reasonable behaviour.

Incidentally, maybe we could have customizable abbrevs? Eg Signatures(; kwargs...).

Yes, kind of setup already do be able to do something like that if we want to allow customisation. It's just not really been needed til now. So you interpolate a $(MethodSignatures(; type_unnamed_args = true)) in your docstrings instead of the default one. (Name of option TBD).

DocStringExtensions.jl/src/abbreviations.jl

Lines 293 to 311 in ec66ad4

	struct MethodSignatures <: Abbreviation end
	"""
	An [`Abbreviation`](@ref) for including a simplified representation of all the method
	signatures that match the given docstring. See [`printmethod`](@ref) for details on
	the simplifications that are applied.
	# Examples
	The generated markdown text will look similar to the following example where a function `f`
	defines method taking two positional arguments, `x` and `y`, and two keywords, `a` and the `b`.
	````markdown
	```julia
	f(x, y; a, b...)
	```
	````
	"""
	const SIGNATURES = MethodSignatures()