Bug #4058: Javadoc missing inherited public methods from abstract (default package access) class - Saxon - Saxonica Developer Community

Actions

Send by e-mail Copy link

Bug #4058

closed

Javadoc missing inherited public methods from abstract (default package access) class

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

Status:

Closed

Priority:

Normal

Assignee:

Debbie Lockett

Category:

Documentation

Sprint/Milestone:

Start date:

2018-11-30

Due date:

% Done:

100%

Estimated time:

Legacy ID:

Applies to branch:

9.8, 9.9

Fix Committed on Branch:

9.8, 9.9

Fixed in Maintenance Release:

9.9.1.1

Platforms:

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

History
Notes
Property changes

Actions

Copy link

Updated by Debbie Lockett almost 6 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&lt;java.net.URI,
                                                net.sf.saxon.s9api.Destination&gt;)</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.)

Actions

Copy link

Updated by Debbie Lockett almost 6 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

Actions

Copy link

Updated by Debbie Lockett almost 6 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

Actions

Copy link

Updated by Debbie Lockett almost 6 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)".

Actions

Copy link

Updated by Debbie Lockett almost 6 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.

Actions

Copy link