I completely agree. I never understood the argument of docs getting out of sync. If an organization prioritizes documentation then the comments are just as likely to stay in sync as the variables.
It's the easiest to keep in sync. It lives in the code it documents. It's in the same version control repo and the same version of the source building a binary can build the docs. If it ever does get out of sync with the code it's the most straightforward to fix because it's the same process for fixing an issue in the code itself.
Tests are not documentation. They only test a very limited "what" or "how" and give no explanation of "why". If it's closed source software and you're only shipping a binary, the tests do not go with the binaries so they're meaningless to third parties. Sample code isn't much better. Without the organizational pressure to keep it in sync with the code it's demoing and "why" explanations it doesn't provide a lot of useful insight for third parties.