RFC: Local Javadoc Linking

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

RFC: Local Javadoc Linking

Daniel Solano Gómez-2
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

attachment0 (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Local Javadoc Linking

Hanno Meyer-Thurow
On Fri, 23 Oct 2009 11:22:30 -0500
Daniel Solano Gómez <[hidden email]> wrote:

> Hello, all,

Hi there!

> I have come up with an initial implementation for this and would like to
> get some feedback from other people. ...

> 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

There are two things in the eclass patch I would fix. ;)
1. I recommend the subshell call '$(...)' instead of the old-style '`...`'.
2. There is an hamcrest comment in java-ant_link-javadoc() ?!

> 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.

I would add 'doc? ( dev-java/java-sdk-docs:${whatever build vm is used} )'
to java-pkg-2.eclass. But I guess then many will complain. :D

My two cents. :)


Regards,
Hanno

Reply | Threaded
Open this post in threaded view
|

Re: RFC: Local Javadoc Linking

Petteri Räty-2
In reply to this post by Daniel Solano Gómez-2
Daniel Solano Gómez wrote:
>
> 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.
>

I think we could have two use flags:
- doc: build javadoc and link to whatever is installed
- javadoc-deep: pull in all deps with [javadoc-deep?]

Better naming suggestions for the second use flag are welcome.

Regards,
Petteri


signature.asc (270 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: RFC: Local Javadoc Linking

Hanno Meyer-Thurow
On Sat, 24 Oct 2009 15:50:10 +0300
Petteri Räty <[hidden email]> wrote:

> I think we could have two use flags:
> - doc: build javadoc and link to whatever is installed
> - javadoc-deep: pull in all deps with [javadoc-deep?]
>
> Better naming suggestions for the second use flag are welcome.

Instead of naming it javadoc-deep maybe name it javasdk-api or javaapi-link, or alike?
That is what you asked for, right?

Or still the simple way to pull in all docs with the doc use flag. :P

And I do not like the approach for the first use flag.
I just do not like automagic. ;)
O well ...


Regards,
Hanno