#625 Added support for displaying overload documentation in the rendered docs, as requested in #529.
While I see the interest and potential usefulness of this featre, I personally have to disagree with the issue author saying:
#297 did the opposite of what the author of any moderately complex overloaded signature wants: it removed it from the docs.
Sometimes, you want overloads to be documented. But oftentimes overloads have a type-meaning that can be way better described in words. Take the following overloads for example:
What do they mean ? This is hardly readable for any developer. But these overloads simply mean embed and embeds are mutually exclusive. file and files are mutually exclusive.
And it is way simpler to write actual documentation for saying this than reading overloads which only clutter the documentation.
I don't want to question that anyone might find utility in this feature, but because of its impact I believe that there should at the very least be an opt-out setting/option.
cc @Lulalaby
#625 Added support for displaying overload documentation in the rendered docs, as requested in #529.
While I see the interest and potential usefulness of this featre, I personally have to disagree with the issue author saying:
Sometimes, you want overloads to be documented. But oftentimes overloads have a type-meaning that can be way better described in words. Take the following overloads for example:
What do they mean ? This is hardly readable for any developer. But these overloads simply mean
embedandembedsare mutually exclusive.fileandfilesare mutually exclusive.And it is way simpler to write actual documentation for saying this than reading overloads which only clutter the documentation.
I don't want to question that anyone might find utility in this feature, but because of its impact I believe that there should at the very least be an opt-out setting/option.
cc @Lulalaby