Project

Profile

Help

http://saxonica.com/html/documentation/javadoc/net/sf/saxon/lib/OutputURIResolver.html mentions AbstractXsltTransformer not listed in all classes document

Added by Martin Honnen almost 5 years ago

http://saxonica.com/html/documentation/javadoc/net/sf/saxon/lib/OutputURIResolver.html says

and a high-level counterpart at the s9api level, AbstractXsltTransformer.setResultDocumentHandler(Function) and AbstractXsltTransformer.setResultDocumentHandler(Function).

I know of the setResultDocumentHandler method of Xslt30Transformer. Is there also a class AbstractXsltTransformer? It doesn't seem to appear in the class list of the API documentation http://saxonica.com/html/documentation/javadoc/allclasses-noframe.html.


Replies (2)

RE: http://saxonica.com/html/documentation/javadoc/net/sf/saxon/lib/OutputURIResolver.html mentions AbstractXsltTransformer not listed in all classes document - Added by Michael Kay almost 5 years ago

It seems the class AbstractXsltTransformer is there in the XML version of the documentation:

http://saxonica.com/documentation/index.html#!javadoc/net.sf.saxon.s9api/AbstractXsltTransformer

but not in the static HTML version. We need to look at why this might be. It's presumably because of the visibility of the class (package private).

RE: http://saxonica.com/html/documentation/javadoc/net/sf/saxon/lib/OutputURIResolver.html mentions AbstractXsltTransformer not listed in all classes document - Added by Debbie Lockett over 4 years ago

Indeed, by design, the package-private class net.sf.saxon.s9api.AbstractXsltTransformer is included in the XML version of the documentation, but not the HTML documentation. This is due to the fix for bug #4058. The bug problem was that methods such as setResultDocumentHandler on XsltTransformer and Xslt30Transformer (inherited from AbstractXsltTransformer) were entirely missing from the XML documentation. (Note that inherited methods on subclasses such as these are not included on the subclass pages in the XML documentation, instead it is necessary to look up the inheritance tree. In contrast, the HTML documentation pages do always include all inherited methods.)

The actual problem here is that the intended javadoc links are not working - in fact not in the HTML documentation nor the XML documentation. Here, the source javadoc comment in OutputURIResolver.java says:

and a high-level counterpart at the s9api level, {@link net.sf.saxon.s9api.Xslt30Transformer#setResultDocumentHandler(Function)} and {@link net.sf.saxon.s9api.XsltTransformer#setResultDocumentHandler(Function)}.

In the HTML documentation (generated using the standard javadoc) these references are both "resolved" to net.sf.saxon.s9api.AbstractXsltTransformer.setResultDocumentHandler(Function). Then since AbstractXsltTransformer is a package-private class, it does not appear in the HTML documentation, so we end up with no links. Which is not useful.

Meanwhile, in the XML documentation (generated using a javadoc target which uses a custom jeldoclet) the references are left intact. For instance, we then get a link to javadoc/net.sf.saxon.s9api/Xslt30Transformer@setResultDocumentHandler. But (as noted above) the setResultDocumentHandler method is only included on the AbstractXsltTransformer page not the Xslt30Transformer page. So then the links don't actually work here either!

I don't know how we can actually get these links right, so I think the best solution is to just amend the {@link}s in the source and make them less ambitious, i.e.:

and a high-level counterpart at the s9api level, using the setResultDocumentHandler() method on {@link net.sf.saxon.s9api.Xslt30Transformer} and {@link net.sf.saxon.s9api.XsltTransformer}.

Committed on 9.9 and 10.0 dev branches. Online 9.9 documentation will be updated with the next maintenance release.

    (1-2/2)

    Please register to reply