I don't have the text for this FAQ entry, but at least I got from Niels that
his package libfreemarker is a good example.
The idea is to have an FAQ item related to this text in section 2.4 of policy:
"Java library packages should compile the javadoc API of the library. The API
must link against the javadoc API of the libraries it depends on. This
includes the core java classes, which are provided by default-jdk-doc. The API
must be registered with doc-base and must be installed in
/usr/share/doc/<package>/api/ or /usr/share/doc/<package>/api-<component>/."