Bug #3795: Broken javadoc links - Saxon - Saxonica Developer Community

Actions

Send by e-mail Copy link

Bug #3795

closed

Broken javadoc links

Added by Debbie Lockett almost 6 years ago. Updated over 5 years ago.

Status:

Closed

Priority:

Low

Assignee:

Debbie Lockett

Category:

Documentation

Sprint/Milestone:

Start date:

2018-05-23

Due date:

% Done:

100%

Estimated time:

Legacy ID:

Applies to branch:

9.8, trunk

Fix Committed on Branch:

9.8, trunk

Fixed in Maintenance Release:

9.8.0.14

Platforms:

Description

Some javadoc links in the documentation come from {@link} markup in the Java comments. If the class name is only given in abbreviated form, rather than the fully qualified class name, then the link does not work in the interactive XML documentation.

e.g. the first paragraph at http://www.saxonica.com/documentation/index.html#!javadoc/net.sf.saxon.z/IntToIntArrayMap is

"An implementation of IntToIntMap that relies on serial searching, and is therefore optimized for very small map sizes" which contains a link for IntToIntMap, but this doesn't work. (Note there is working link directly above because IntToIntMap is the implemented interface).

Links should be given as package.class#member (see https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#link).

https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#package.class says:

"This package.class#member name can be either fully-qualified, such as java.lang.String#toUpperCase() or not, such as String#toUpperCase() or #toUpperCase()."

So the different forms are:

Referencing a member of the current class, e.g. #method(Type, Type,...)
Referencing another class in the current or imported packages, e.g. Class#method(Type argname, Type argname,...)
Referencing an element in another package (fully qualified), e.g. package.Class#constructor(Type, Type,...)

It seems that we handle cases 1 and 3, but not 2. See <xsl:template match="tag[@kind]" mode="jdc"> in jdc-body.xsl.

Actions

Copy link

Updated by Debbie Lockett almost 6 years ago

Status changed from New to In Progress

The source XML for the javadoc section in the documentation application is generated in two steps: first a custom doclet (jeldoclet.jar) is used to generate XML including jeldoclet-out.xml (see target product-javadoc-jd in build-jd), and this is then processed using the chunk-javadoc.xsl stylesheet (build target product-xsljavadoc) to produce the contents of the javadoc-xml directory (as used in the app).

To fix the broken links we need information about the imported packages for a class - which is available after the first step, but not the second. So the chunk-javadoc.xsl stylesheet should be updated to capture this information as required. i.e. When a link uses a class name which is not fully qualified, the transform should update it to be fully qualified (by checking against the imported classes/packages). This processing is actually already happening for links which use local method names (#method), so basically we just need to extend the coverage. Note that for class links it is also necessary to check inner classes, as well as imported classes (e.g. to fix the link to the inner class LicensedFeature from javadoc/net.sf.saxon/Configuration@checkLicensedFeature).

Fixes committed in build98/jd-build/chunk-javadoc.xsl and build99/jd-build/chunk-javadoc.xsl

During this work, I also realised that the application stylesheet jdc-body.xsl currently handles all elements as links, but really we should check the tag/@kind attribute to distinguish between the two possible cases: 'see' and 'code'. Links should be produced from tag[@kind='see']@, but @tag[@kind='code'] should just wrap the content in code tags.

Fixes committed under 9.8 and 9.9. dev branches.

The online 9.8 documentation should be regenerated and updated with these fixes in the next release.

Actions

Copy link

Updated by Debbie Lockett almost 6 years ago

Description updated (diff)
Status changed from In Progress to Resolved
Fix Committed on Branch 9.8, trunk added

A couple of further fixes have been made:

Update chunk-javadoc.xsl so that <tag kind="code"> elements are directly converted to <code> wrappers (rather than attempting to resolve references and produce links, as for <tag kind="see">).
Tidy up comments in Java source to use {@code } rather than {@link } in some places (e.g. when referring to UnsupportedOperationException) to address a number of warnings from the product-xsljavadoc build target.
Tidy up comments in Java source which have {link ...} rather than {@link ...}