[tracker1]

It seems that JSDoc generated documents are an example of close to just this... you don't reference the code, you reference the docs. But the docs live inside the code for generation.

If you otherwise have separate documentation that is not generated, if the system/library has any complexity there's a greater chance that documentation doesn't align with implementation and bugs will creep in. That's not to mention stupid developer decisions, such as weird date normalization/structure or similar usage of magic numbers over text keys/flags.