Should `TYPEDSIGNATURES` include types for keyword arguments?

[bzinberg]

I find it very helpful to include $(TYPEDSIGNATURES) at the top of my function docstring template. I'm wondering why type annotations are included in positional arguments but not keyword arguments? I would have expected/preferred to have type annotations appear in the docstring everywhere that they appear in the actual function signature. That's how it was in the initial proposal in https://github.com/JuliaDocs/DocStringExtensions.jl/issues/20, and I haven't been able to find any further discussion on the topic.

[bzinberg]

have type annotations appear in the docstring everywhere that they appear in the actual function signature

Along those lines, it might also make sense to not show type annotations for arguments whose type is Any.

[kdheepak]

I'm wondering why type annotations are included in positional arguments but not keyword arguments?

I have to double check if this is the case but I think keyword argument types were not part of the Julia docstrings typesig. I have some thoughts about how to do this better, so I'll look into it for the next PR related to $TYPEDSIGNATURES.

it might also make sense to not show type annotations for arguments whose type is Any.

I think this makes sense.

[bzinberg]

I have to double check if this is the case but I think keyword argument types were not part of the Julia docstrings

Yeah, looks like the current docs code omits the types of keyword arguments, and (incorrectly, AFAICS) refers to them as "optional" arguments.

[bzinberg]

It looks like the docs question might be partly (but not completely, I think) coupled with decisions about how Julia dispatches on keyword arguments, as in e.g. https://github.com/JuliaLang/julia/issues/34514#issuecomment-578934215. Thanks @kdheepak for looking into it.

[MichaelHatherly]

coupled with decisions about how Julia dispatches on keyword arguments

Yes, correct. We never bothered storing anything related to keywords since they don't really play a part in dispatch in the usual way. Extracting the keyword arg types from the method objects should be possible, though I've not looked into that in a while.

it might also make sense to not show type annotations for arguments whose type is Any.

Seems reasonable to me.