Bug #4058
closed
Javadoc missing inherited public methods from abstract (default package access) class
100%
Description
The javadoc in the documentation app has information missing. For example:
Xslt30Transformer and XsltTransformer extend the abstract class net.sf.saxon.s9api.AbstractXsltTransformer. AbstractXsltTransformer has the default package level access (it is not public, private, or protected), and contains public methods which are inherited by Xslt30Transformer and XsltTransformer. Since AbstractXsltTransformer is not public, it does not appear in the javadoc. But the inherited public methods are not included in the documentation app javadoc for Xslt30Transformer and XsltTransformer either (note that they do appear in the HTML javadoc).
Updated by Debbie Lockett over 5 years ago
This seems to be a jeldoclet issue.
Investigating further, in fact the jeldoclet InheritanceHandler does get information about the methods on extended classes, which is added to the class/extends/interface element for the subclass in jeldoclet-out.xml. e.g.
<extends>
<interface fulltype="net.sf.saxon.s9api.AbstractXsltTransformer" type="AbstractXsltTransformer">
<methods>
<method>setBaseOutputURI(java.lang.String)</method>
<method>getBaseOutputURI()</method>
<method>setURIResolver(javax.xml.transform.URIResolver)</method>
<method>getURIResolver()</method>
<method>setErrorListener(javax.xml.transform.ErrorListener)</method>
<method>getErrorListener()</method>
<method>setResultDocumentHandler(java.util.function.Function<java.net.URI,
net.sf.saxon.s9api.Destination>)</method>
<method>setMessageListener(net.sf.saxon.s9api.MessageListener)</method>
<method>setMessageListener(net.sf.saxon.s9api.MessageListener2)</method>
<method>getMessageListener()</method>
<method>getMessageListener2()</method>
<method>setAssertionsEnabled(boolean)</method>
<method>isAssertionsEnabled()</method>
<method>setTraceListener(net.sf.saxon.lib.TraceListener)</method>
<method>getTraceListener()</method>
<method>setTraceFunctionDestination(net.sf.saxon.lib.Logger)</method>
<method>getTraceFunctionDestination()</method>
<method>setSchemaValidationMode(net.sf.saxon.s9api.ValidationMode)</method>
<method>getSchemaValidationMode()</method>
<method>setInitialMode(net.sf.saxon.s9api.QName)</method>
<method>getInitialMode()</method>
<method>getUnderlyingController()</method>
<method>getDestinationReceiver(net.sf.saxon.trans.XsltController,
net.sf.saxon.s9api.Destination)</method>
</methods>
</interface>
</extends>
But after the chunk-javadoc.xsl transform, this information is lost, e.g. the net.sf.saxon.s9api.xml file just has:
<extends>
<interface fulltype="net.sf.saxon.s9api.AbstractXsltTransformer" type="AbstractXsltTransformer"
/>
</extends>
The method details are not complete, but at least having this information would be a start!
The class AbstractXsltTransformer is not included in the jeldoclet output (since only public classes are included), but maybe it should be; to get the full method details (comments, parameters, exceptions, etc.)
Updated by Debbie Lockett over 5 years ago
In order to include "package" access classes such as AbstractXsltTransformer in the jeldoclet output, rather than make internal changes in the jeldoclet source, what is required is a change in the way the jeldoclet is called from the javadoc Ant task. The javadoc Ant task has an attribute access - used to specify the access mode: one of public, protected, package, or private. We currently use access="protected", which means "Show protected/public classes and members (default)", but updating this to access="package" means "Show package/protected/public classes and members".
Rather than showing the inherited public methods, etc. on subclasses as in the HTML javadoc, this change means that the package access classes are themselves included in the documentation app javadoc. But this seems like a reasonable solution, especially as it is so simple (and avoids the need for lots more work).
For reference, the list of package-private newly included classes (on 9.9) is as follows:
- com.saxonica.ee.domino.SiblingIterator
- com.saxonica.ee.domino.PrecedingSiblingIterator
- com.saxonica.ee.domino.PrecedingIterator
- com.saxonica.ee.domino.FollowingIterator
- com.saxonica.ee.domino.DescendantIterator
- com.saxonica.ee.optim.SmallSearchableValue<T extends net.sf.saxon.om.Item<?>>
- com.saxonica.ee.s9api.SchemaValidatorImpl.ValidationCompletionAction
- com.saxonica.ee.s9api.SchemaValidatorImpl.ValidationTask
- com.saxonica.ee.stream.om.AttributeIterator
- com.saxonica.ee.validate.SelectorWatch.ValueEntry
- net.sf.saxon.Transform.TransformThread
- net.sf.saxon.dom.DOMImplementationImpl
- net.sf.saxon.dom.DOMAttributeMap
- net.sf.saxon.jaxp.AbstractTransformerImpl
- net.sf.saxon.regex.RECompiler.BackReference
- net.sf.saxon.s9api.MessageListenerProxy
- net.sf.saxon.s9api.MessageListener2Proxy
- net.sf.saxon.s9api.ItemType.BuiltInAtomicItemType
- net.sf.saxon.s9api.ConstructedItemType
- net.sf.saxon.s9api.AbstractXsltTransformer
- net.sf.saxon.s9api.streams.AxisStep
- net.sf.saxon.serialize.codenorm.UnicodeDataParserFromXML
- net.sf.saxon.serialize.codenorm.UnicodeDataGenerator
- net.sf.saxon.tree.linked.TreeEnumeration
- net.sf.saxon.tree.linked.PrecedingSiblingEnumeration
- net.sf.saxon.tree.linked.PrecedingOrAncestorEnumeration
- net.sf.saxon.tree.linked.PrecedingEnumeration
- net.sf.saxon.tree.linked.ParentNodeImpl
- net.sf.saxon.tree.linked.FollowingSiblingEnumeration
- net.sf.saxon.tree.linked.FollowingEnumeration
- net.sf.saxon.tree.linked.ChildEnumeration
- net.sf.saxon.tree.linked.AttributeEnumeration
- net.sf.saxon.tree.linked.AncestorEnumeration
- net.sf.saxon.tree.tiny.TinyProcInstImpl
- net.sf.saxon.tree.tiny.TinyCommentImpl
- net.sf.saxon.tree.tiny.SiblingIterator
- net.sf.saxon.tree.tiny.PrecedingSiblingIterator
- net.sf.saxon.tree.tiny.PrecedingIterator
- net.sf.saxon.tree.tiny.NamedChildIterator
- net.sf.saxon.tree.tiny.GraftingDescendantIterator
- net.sf.saxon.tree.tiny.FollowingIterator
- net.sf.saxon.tree.tiny.DescendantIteratorSansText
- net.sf.saxon.tree.tiny.DescendantIterator
- net.sf.saxon.tree.tiny.AttributeIterator
Updated by Debbie Lockett over 5 years ago
- Status changed from New to In Progress
As noted above, the change to use access="package" for the javadoc Ant task adds many package-private classes (and one interface) to the documentation. Not all of these actually need to be added: e.g. the package-private interface com.saxonica.ee.s9api.SchemaValidatorImpl.ValidationCompletionAction has no implementing classes, so it is not actually relevant to users.
Package-private members of classes, interfaces and enums are also added, but these are not relevant to users.
When all members of a package-private class are package-private (or private), again the class is not relevant: e.g. net.sf.saxon.serialize.codenorm.UnicodeDataParserFromXML.
To prevent this unnecessary bloat, I think it is worth making changes in the chunk-javadoc.xsl stylesheet to filter out the package-private classes and members which are not actually relevant. So all package-private members are removed, and we filter package-private classes and interfaces so that one is only included if it has some public subclasses or implementing classes, and some non-package-private members.
By adding these filters, the list of package-private newly included classes (on 9.9) is reduced to just the following:
- net.sf.saxon.jaxp.AbstractTransformerImpl (which has subclasses StreamingTransformerImpl, TransformerImpl)
- net.sf.saxon.s9api.AbstractXsltTransformer (subclasses Xslt30Transformer, XsltTransformer)
- net.sf.saxon.tree.linked.ParentNodeImpl (subclasses DocumentImpl, ElementImpl)
Note that this issue is not new in 9.9. I think it is probably worth updating the 9.8 javadoc too, but maybe not earlier. The package-private classes which get added for 9.8 are:
- net.sf.saxon.jaxp.AbstractTransformerImpl
- net.sf.saxon.tree.linked.ParentNodeImpl
Updated by Debbie Lockett over 5 years ago
- Applies to branch 9.8 added
Discovered a further related issue in chunk-javadoc.xsl in the "implementing-classes" key. This key is used to find the classes which implement an interface, by looking at the extends/inherits/interface/@fulltype and implements/interface/@fulltype descendants of each class. The problem was that the implemented interfaces in a nested class (e.g. HTMLIndenter.HTMLNameClassifier) were wrongly being assigned to the enclosing class (e.g. HTMLIndenter). Fixed by updating the use attribute on the xsl:key: use="(extends/descendant::inherits/interface/@fulltype, implements/descendant::interface/@fulltype)" rather than use="(.//extends/inherits/interface/@fulltype, .//implements/interface/@fulltype)".
Updated by Debbie Lockett over 5 years ago
Updates committed on 9.9 and 9.8 branches:
- build9X/build-jd.xml - to use access="package" for javadoc target
- build9X/chunk-javadoc.xsl - to use [@visibility ne 'package-private'] filter as appropriate; implementing-classes key correction
- latest9.X/userdoc/saxon9/viewer_app/xsl/jdc-body.xsl - tidy up modifiers
Not yet updated online.
Updated by Debbie Lockett about 5 years ago
- Fix Committed on Branch 9.8, 9.9 added
- Fixed in Maintenance Release 9.9.1.1 added
Updated online 9.9 documentation (including javadoc) with 9.9.1.1. release.
Updated by Debbie Lockett about 5 years ago
- Status changed from In Progress to Closed
- % Done changed from 0 to 100
Belatedly updated 9.8 javadoc documentation (and viewer_app/xsl/jdc-body.xsl) online; so this bug can now be closed.
Please register to edit this issue
.