I have something that should surely be a fairly common need for documentation ...
I am implementing a rather significant base of Java library code, which, among other things, includes various classes that should be exposed to the caller / actuator at an appropriate level of abstraction. At the same time, the code base contains, of course, various internal classes, interfaces, and other abstractions that the library user does not need to know in order to use the API.
Many other API libraries make a mistake there by simply dropping everything into Javadocs and leaving it to the user to find out what objects and entities they really should have as the caller through some combination of guesses, output, and, if you're lucky, a code example .
I do not want to be in the same position. I would like to have an “internal” set of Javadocs that display the full extent of the code base, and an “external” set of Javadocs should clearly tell developers the characteristics of the classes that they really need to use in order to get their work done. I don’t need or don’t want to stir up the waters with various internal abstractions that they don’t need to see or know - they don’t need to know how it all works under the hood, and it just confuses and misdirects them, which makes the learning process very ineffective API
How can i do this? Is there a known combination of javadoc arguments and maybe some annotations that can do this?
Thanks so much for your attention!