Project

Profile

Help

Actions
Send by e-mail Copy link

Bug #6293

closed

XML javadoc for com.saxonica.functions.extfn.EXPathArchive is broken

Added by Debbie Lockett 5 months ago. Updated 5 months ago.

Status:
Closed
Priority:
Low
Assignee:
Debbie Lockett
Category:
Documentation
Sprint/Milestone:
-
Start date:
2023-12-15
Due date:
% Done:

100%

Estimated time:
Legacy ID:
Applies to branch:
11, 12, trunk
Fix Committed on Branch:
11, 12, trunk
Fixed in Maintenance Release:
Platforms:

Description

Something has gone wrong for the documentation of the com.saxonica.functions.extfn.EXPathArchive package in the XML javadoc. The documentation for the classes isn't found (e.g. links from https://www.saxonica.com/documentation12/index.html#!javadoc/com.saxonica.functions.extfn.EXPathArchive result in "Type com.saxonica.functions.extfn.EXPathArchive.Archive is not defined here.").

Actions
Copy link
 #1

Updated by Debbie Lockett 5 months ago

The problem arises because we have a package name which is not all lower case (which is the standard convention). This then causes confusion for the class members because they are wrongly assumed to be nested classes. It is assumed that com.saxonica.functions.extfn.EXPathArchive.Archive refers to a nested class EXPathArchive.Archive in package com.saxonica.functions.extfn, rather than a class Archive in the package com.saxonica.functions.extfn.EXPathArchive.

This falls over in the f:anchor-navigation function in viewer_app.xsl where we look for upper case initials to work out the path:

    <xsl:variable name="tokens" select="tokenize($pageref,'\.')" as="xs:string*"/>
    <xsl:variable name="paths" as="xs:string*"
                        select="for $t in 1 to count($tokens),
                                    $ch in substring($tokens[$t],1,1) return
                                    if (upper-case($ch) eq $ch) then
                                    concat('/',$tokens[$t]) else concat('.',$tokens[$t])
                                    "/>
Actions
Copy link
 #2

Updated by Debbie Lockett 5 months ago

  • Status changed from New to In Progress
  • Fix Committed on Branch 11, 12, trunk added

Relatedly, the XML javadoc for double nested classes (e.g. FilterExpression.FilterExprElaborator.PositionalFilteredIterator and FilterExpression.FilterExprElaborator.SimpleFilteredIterator in package net.sf.saxon.expr, added in saxon12) is also broken.

Note that com.saxonica.functions.extfn.EXPathArchive is the only Saxon package with a name which is not all lower case.

Fixes committed in chunk-javadoc.xsl: to avoid '.' in class names in the generated files javadoc-tree.xml and javadoc-types.xml; and recognise com.saxonica.functions.extfn.EXPathArchive as a package, and get its members names right (i.e. avoid 'EXPathArchive.' in member and type names). Corresponding fixes committed in viewer_app.xsl to correctly handle double nested classes in the apidoc-subpage template; and add a special case to recognise com.saxonica.functions.extfn.EXPathArchive as a package in the f:anchor-navigation function.

Committed on main, saxon12, and saxon11 branches.

Actions
Copy link
 #3

Updated by Debbie Lockett 5 months ago

  • Status changed from In Progress to Closed
  • % Done changed from 0 to 100

To fix the XML documentation online, updates pushed to www-saxonica-com for documentation12 and documentation11:

  • javadoc-xml/packages/com.saxonica.functions.extfn.EXPathArchive.xml
  • javadoc-xml/javadoc-tree.xml
  • javadoc-xml/javadoc-types.xml
  • xsl/viewer_app.sef.json

Note that for javadoc-tree.xml and javadoc-types.xml, I have edited the files by hand (comparing to what is now generated using chunk-javadoc.xsl) to ensure that only changes relevant to this bug fix are included (i.e. not other API changes in development since the last maintenance releases).

Please register to edit this issue

Actions
Send by e-mail Copy link

Also available in: Atom PDF