[gentoo-java] RFC: Local Javadoc Linking

[Daniel Solano Gómez]

Hello, all,

I recently created some new ebuilds for the hamcrest matcher libraries.
In my ebuilds, I had added some functionality to so that the Javadoc=20
that is created will link to locally-installed documentation.  On
#gentoo-java, Betelgeuse recommended I that I generalise the
functionality so that it can be applied more generally.  I believe this
also the topic of bug 145750.

I have come up with an initial implementation for this and would like to
get some feedback from other people.  My implementation is broken up
into two parts:

1. An additional script to be added to javatoolkit:  This was necessary
as the existing xml-rewrite* scripts seem to concentrate on manipulating
attributes, but this task required manipulating elements.  This script
is available as a patch to javatoolkit-0.3.0 available at:
https://bugs.gentoo.org/attachment.cgi?id=3D207944

2. Modifications to the java-ant-2.eclass:  I added a new function
java-ant_link-javadoc() that does the work of looking up local
documentation and calling the helper script.  I also added a hook to the
function from java-ant-2_src-configure().  This patch is available at:
https://bugs.gentoo.org/attachment.cgi?id=3D207945


How it Works
------------

When java-ant_link-javadoc() is called, it first checks to see if
java-sdk-docs is installed, and if so gets the path to the API
documentation.

Next, it looks at the environment variable JAVA_ANT_DOCPATH, which by
default is copied from EANT_GENTOO_CLASSPATH.  It uses java-config to
see if the JAVADOC_PATH is set for the package.  If so, it adds it to
the list of paths to documentation.

Finally, it uses the javadoc-helper script with the found paths.  This
script searches for <javadoc> elements, strips them of any existing link
information, and injects the link information passed from the command
line.


Limitations
-----------

1. The method above is opportunistic.  If the user does not have any
local API documentation, none is used.  It is possible to modify the
script to ensure that an ebuild's dependencies have the doc USE flag
enabled, but that seems a bit heavy-handed to me.

2. This method clobbers any existing link information in the build.xml.
I did things this way because it was simplest.  I do not know how
Javadoc deals with overlapping packagelist information.  It may be
desirable to add a flag that disables this functionality for a given
ebuild.

3. This method does not link to external documentation.  At least, if
its not listed in a package.env.  Allowing ebuild writers to define a
JAVADOC_URL to be added to package.env could allow it.  If the
packagelist could be found locally, the javadoc-helper tool can even
perform the linking offline.

4. The SDK link uses the most recent version of java-sdk-docs.  Perhaps
it would help if script used the same version of the documentation as
the JDK it is using.


Other Notes
-----------

1. Since this is the first time I get into the details of how portage
works and modifying eclasses, I appreciate any comments on how my
implementation can be improved.  For example, is there a better place to
hook into java-ant_link-javadoc() script?

2. The code is not thoroughly tested.  I have not tried it with any
alternative package managers.  I appreciate any feedback on how to
ensure that it is robust.  Also, I am not a Python coder, so there may
be errors lurking of which I am unaware.

3. In my Python code I tried to use the principles in Robert Martin's
book 'Clean Code'.  Namely, the proliferation of many small, cohesive
methods.  I do not know what others think of it, but it was worth
trying.


I look forward to any feedback.  I have attached the patches to bug
145750 for review.  Please let me know if there is anything I can do to
improve this functionality.

Sincerely,

Daniel Solano Gómez