I cannot remember where I first heard this quote, but it has always resonated with me. The code should tell you what is happening, but the comments can tell you why.
And you're right, going slightly verbose on comments on public interfaces of your API may only be allowed only if it's for documentation generation purpose. Libraries like Typedoc for Typescript (a little bit OOT here) generate documentations extracted from the comments, as other people may have mentioned.
I think it comes from blog.codinghorror.com/code-tells-y... which I wholeheartedly agree.
And you're right, going slightly verbose on comments on public interfaces of your API may only be allowed only if it's for documentation generation purpose. Libraries like Typedoc for Typescript (a little bit OOT here) generate documentations extracted from the comments, as other people may have mentioned.
Ahh it was definitely coding horror! Thanks!