This post exists to stop people (possibly including myself) spending hours being thoroughly confused as to why

override_dh_installdocs:
dh_installdocs --link-doc=package
l
is not working. In fact it probably is working but your package-doc.javadoc probably looks something like:

docs/api

rather than like:

docs/api /usr/share/doc/package/api

and hence jh_installjavadoc is correctly creating the /usr/share/doc/package-doc/ directory when really you didn’t want that to happen and so dh_installdocs –link-doc silently ignores your instruction as it doesn’t make sense in context.

Relatedly I have ‘finished’ packaging JEval for Debian partly using the instructions on packaging java packages using git. It just needs some further testing and to be uploaded and sponsored.
(I am packaging the dependencies of my Part II Project)