Why is it Convention to Repeat Function Signatures in Docstrings

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 should maintain. You can then sometimes want to document methods that have special cases as separate sections, but you can also omit documentation for the more specific methods if they perfectly implement the general behaviors.

8 Likes