Javadoc needs to know the paths to others libraries' javadoc api documents in order to correctly link the files. I suggest to add a new function to one of the java eclasses that does this task.
Definitely not portage folks' business...
Created attachment 95572 [details] A possible implementation for that function This is an implementation of that function in a new eclass file. I tested it, and works for me. It should be renamed and moved to a different {existing} java-something eclass, though.
I think eclass shouldn't do this package.env parsing itself, this should be implemented in java-config - currently it can tell you arbitrary env value from active vm, it should be extended to give arbitrary env value from given package. An eclass function would just wrap this, possibly giving a warning when the env value wasn't there (package wasn't build with doc useflag or doesn't even support it). Warning should be enough, no need to die, this is not fatal. Also, can you give an example on how this info is passed to javadoc directly and when using ant?
I agree about the java-config thing. However, doing it directly with a function was very easy, and the change to be done is smaller. Doing it the way you say, you have to change java-config and add the wrapper function. Javadoc has the following two flags: -link <url> Create links to javadoc output at <url> -linkoffline <url> <url2> Link to docs at <url> using package list at <url2> Javadoc stores a file with package information. When using these link flags, it tries to find those info files and uses the url when a Class, method, etc. points to anything that belongs to the linked packages. The javadoc ANt task has a link property. By setting it to a right path, it will use it as the parameter to the link flag. In my case, I used an environment variable in the ebuild and got its value from the build.xml file. You can patch build.xml as well but, in my oppinion, the first way is easier. Anyway, the ant eclass rewrites these build.xml files. I think adding the right javadoc link property should be automatically done when patching those files. However, this change is even bigger and, in my case, having the find-javadoc-urls function available is enough.
Here's an example of a javadoc task that actually works (its part of MTP's build.xml file). See bug #117108 to read the ebuilds ifyou need to (they do include this find-javadoc-urls function, under a different name): <property environment="env" /> <property name="JSAP_API" value="${env.JAVADOC_LINK}" /> <target name="doc" depends="compile" > <mkdir dir="docs" /> <javadoc packagenames="mtp.*" sourcepath="${src}" destdir="docs" link="${JSAP_API}" classpath="${lib}/JSAP_1.03a.jar" /> </target>
Hm what if you depend on more packages, thus need links to more packages? Seems that javadoc does this by multiple -link arguments. In ant that probably means several nested <link> elements instead of one link="" attribute of <javadoc>. Not sure if that can be done automatically...
Well, it can be done in a more or less automatic way, depending on whether you are patching the build.xml files or using environment variables. The former case is easier: for each dependency, find the location of its javadoc files and add a nested link tag for that path (if $(build_with_use doc dependency)) to the javadoc task. The latter is a bit more ugly: you have to add an environment variable for each package, and the build.xml file must manually read each one of those variables, and have a link tag for it. I don't think ANT would accept a concatenation on several paths for a unique LINK href property using separators (i.e. LINK="/usr/share/doc/library1/api:/usr/share/doc/library2/api"). If it does, the automatic solution is straightforward. One more thing: javadoc uses the 'source' property, just like javac does. As I said before, this feature should be (sooner or later) added to the same function that patches the build.xml files.
Ok, I tried to concatenate two different hrefs in the same 'href' attribute to a link but it didn't work (as expected). Definitively, we have to use as many nested link tags as javadoc dependencies are.
Nichoj brought up another problem on IRC. The links to javadocs are very fragile, because the path contains /usr/share/doc/${PF}/ (that's including revision), so any revbump of dependency package would cause the links to be broken for depending package that was merged before.
Yep, that one I knew. First of all, javadoc links can use http refs to api doc. For instance, you can specify href="http://java.sun.com/doc/jdk-1.4.0/html/api" (I don't know if that thing is right, it's just to give an example). That should fix the problem unless the web site address changes. In order to do that, I guess the best way is to write something like JAVADOC_EXTERNAL_HREF="http://..." in package.env, an href that should be in the library's ebuild, and that's the path that other ebuilds would use when setting the link's href. This link is less likely to change between versions. Other possibility is to store javadoc files in a path that doesn't depend on (very) minor version numbers: using /usr/share/doc/jsap-1.3/api instead of /usr/share/doc/jsap-1.3.05/api. That avoids recompilation of reverse dependencies unless there's a change from, for instance, 1.3 to 1.4. A third possibility could be to create a common subdir for all javadoc documentation, with symbolic links to the right paths. It would work in almost every case without needing to recompile after updates, and you can create the links using ${P} as name or maybe something that includes part (major) of the version number.
Created attachment 207944 [details, diff] Patch to dev-java/gentoolkit-0.3.0 to include new javdoc-helper script This patch adds a new script 'javadoc-helper' that can modify a build.xml document to add link information to <javadoc> elements.
Created attachment 207945 [details, diff] Patch to java-ant-2.eclass that handles local Javadoc linking This patch collects a list of paths to locally-installed documentation and uses the javadoc-helper script to modify a build.xml document to link to the local documentation.
I was asked about this bug today. I think we have much bigger fish to fry but I'll put down a couple of thoughts. The ${PF} issue is no longer an issue. I don't know when we started doing it but java-pkg_dojavadoc creates a symlink at /usr/share/${PN}-${SLOT}/api, probably for this very reason. Ant is now on the decline and I don't think we should go out of our way to try and fix up build.xml files. They give us enough trouble already and it seems like more hassle than it's worth. This becomes much easier with Maven as our current strategy involves calling javadoc directly from the eclasses where we can easily include whatever additional arguments we need.
