I am inclined to agree. Unit tests and documentation are two SEPARATE things with different intentions. IMHO, mixing these together harms both. Unit tests are

I am inclined to agree. Unit tests and documentation are two SEPARATE things with different intentions. IMHO, mixing these together harms both. Unit tests are primarily intended for the developers of the library. They do help users, sometimes, when you're trying to work out some fundamental misconception about what the library DOES, but generally speaking the granularity of unit tests is too fine unless you're REALLY digging in. Much better, I think, to spend effort on writing clear documentation. R has a problem with that. Docs typically have overwhelming terse detail followed by anemic examples. Couple this with that fact that R users tend to always be in the middle of something urgent and completely unrelated to writing libraries (like, analyzing data and making decisions based on that data) and you get a recipe for frustration. I find myself referring over and over again to the tidyverse "cheatsheets" [https://posit.co/resources/cheatsheets/ https://posit.co/resources/cheatsheets/]. These show, explicitly and clearly, what the things actually do. I wish someone put that kind of, often graphical, content into the docs for all functions.