I have moderate successful Java library. Problem with documentation is: - it takes effort to write it - there is a split between what documentation describes

I have moderate successful Java library. Problem with documentation is: - it takes effort to write it - there is a split between what documentation describes and reality - it falls behind as new stuff develops, project gets forked, taken over... My solution is to have code examples, that are part of unit tests. Separate folder that describes most common use cases. If documentation is wrong, project does not even compile or test fails. And I can always point to most current version of examples in git branch. I really think any document beyond simple readme.md is overkill for most projects.