Interesting article on API documentation best practices.
The author focuses on web APIs, but I think this article applies to classic APIs (those in our packages or that we generate ourselves for other teams).
In short, it's always advisable to provide two types of documentation: the specifications (the "what") and the API documentation (the "how").
https://inkwright.inc/blog/your-api-reference-is-not-your-api-documentation