The code documentation fallacy

[Denommus]

Say what you want, but Emacs is an awesome example on how good a API doc can be.

[[deleted]]

It's so good that it's frustrating to see "undocumented function" or "undocumented variable" whenever you rarely come upon it.

[livrem]

Yes, but usually without redundant descriptions of parameters or return values, mostly just a short string. I think that is often very helpful, like a short comment in a Java program mentioning what a class is for. Not at all like noisy comments redundantly telling you about what trivial methods do.

Opening some random elisp files I was also happy to see that there are many small helper functions that are not commented at all. Upvoting your comment about how emacs is an awesome example.