Saxon

The dotnetdoc pipeline has been updated (in parsecs.xsl) to include the new generated Feature keys source files: Feature.cs and FeatureKeys.cs. These are generated using tools/featureKeys/FeatureKeysToCSharp.xsl.

I have tidied up the documentation comments in the C# files, with reference to https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments

Note that currently I have eliminated the use of <value> for properties (with get/set methods), because this is not handled when generating page content. Instead we are using <return>, but probably actually we should update the pipeline so that <value> can be used correctly.

Also, we need to make sure that all methods and constructors have comments, else the documentation generation goes wrong. e.g. As Mike spotted, the 9.8 .NET documentation for XdmArray has issues. The documentation lists the constructor from List<XdmValue> twice.

Documented:

• public XdmArray ()
• public XdmArray (XdmValue[] members)
• public XdmArray (List members)
• public XdmArray (List members)

Model.cs code:

• public XdmArray()
• public XdmArray(XdmValue value) - no doc comment for 9.8
• public XdmArray(XdmValue [] members)
• public XdmArray(List members)

9.8 .NET documentation for XdmArray fixed by adding missing comment (as described above). Committed and updated online (XML and HTML versions).

Further patch committed to build99/jd-build/chunk-javadoc.xsl, re case-insensitive ordering (see note 1). Ensure "Nested Classes" are listed in alphabetical order (see http://www.saxonica.com/documentation/index.html#!javadoc/com.saxonica.ee.bytecode/CalculatorCompiler and compare to ordering of "Direct Known Subclasses").

Improving handling of generic types and generic methods:

• Improve handling of generic types (for classes, fields, properties, return type of methods, method parameters, etc.)

Better to do this early in pipeline, so changes made in parsecs.xsl. Split generic types into main type and type parameters, so in names.xml, the following elements can have <type type="T"/> children defining the type of type parameters: interface, class, field, constructor, property, method, param.

Particular improvements for processing methods: to correctly handle methods with return types which are generic, and method arguments with generic types. (This meant some old processing could be removed from later in the pipline (convert-to-jel-package.xsl) which was trying to handle these generic types.)

• Improve handling for generic methods

Extract info in parsecs.xsl, so in names.xml, element <method> can have <paramtypes><type name="T"/></paramtypes> child defining the type parameters for the generic method.

Update jdc-body.xsl (& SEF) to handle difference in syntax between Java and .NET for generic methods: e.g. for .NET public void SetProperty<T> (Feature<T> feature, T value) while for Java public <T> void SetProperty (Feature<T> feature, T value)

• Update merge.xsl & convert-to-jel-package.xsl to pass through these paramtypes and type elements correctly (and add @fulltype.)

Improvements for handling internal API links:

In C# comments these look like e.g. <see cref="InitialMode">

In apidoc.xml they have been resolved e.g. <see cref="P:Saxon.Api.Xslt30Transformer.InitialMode" />

In merge.xsl, these will be converted to <tag kind="see">Saxon.Api.Xslt30Transformer#InitialMode</tag>. Note use of # as separator for methods, fields, properties on classes|interfaces (as used in javadoc XML files).

Note nonstandard syntax used for links to nested classes, and links to javadoc class members (i.e. @cref containing + or #):

• e.g <see cref="Saxon.Api.XsltExecutable+ParameterDetails"/> <see cref="net.sf.saxon.s9api.OccurrenceIndicator#ZERO_OR_MORE"/>

• Note that for each of these, the fully qualified name should be used (in the C# code comment) because they are not actually handled by the compiler, and so won't be resolved. (In fact, get warnings from compiler in csharp-een target, as apidoc.xml is produced. But using this syntax is convenient, and I've not found a better way to handle such links, so I think we just put up with warnings.)

Improve handling for inheritance details for classes, interfaces, and enums.

Recall: a (derived) class cannot extend more than one (base) class; but a class can implement one or more (base) interfaces.

Rather than just using @base (as in names.xml and merged.xml, which is converted to @superclass in convert-to-jel-package.xsl for Saxon.Api.xml) on class | interface | enum; add <implements> and/or <extends> elements with <interface> children (with @fulltype and @type), as used in javadoc XML files. Better to do this as early as possible in pipeline, i.e. in merge.xsl (when it is possible to fully resolve types properly).

Update convert-to-jel-package.xsl and tohtml.xsl to copy/use these elements correctly.

Additional convert-to-jel-package.xsl updates:

• to handle em, b, span tags properly in comments

• update "class-by-name" key to handle nested classes

Various updates in tohtml.xsl (for generating HTML dotnetdoc):

• General update for look (style and some formatting) of HTML dotnetdoc:

Modernise, and move styling from HTML elements into new CSS stylesheet saxon-dotnetdoc.css (note build-n.xml update).

Update top level "Saxon.Api" namespace page, to align info with XML dotnetdoc, and include summary tables for interfaces, classes, enums, and exceptions (as in XML javadoc and dotnetdoc).

• Updates for fixes as in comments above: sorting fixes; handle generic types; show type parameters for generic methods; improve handling of base types.

• Ensure info for subclasses, nested classes, and base class/interfaces is correct (some was missing or muddled).

• Ensure see tag links work correctly:

Improve handling for links to external types (e.g. System types).

Take particular care for local (Saxon HTML dotnetdoc and javadoc) page links depending on depth of HTML page (i.e. top level "Saxon.Api" namespace page, or class|interface|enum page, or nested class page).

Changes committed:

• build99/MyDotNet/doctools/ (convert-to-jel-package.xsl, merge.xsl, parsecs.xsl, tohtml.xsl, + saxon-dotnetdoc.css added)

• build99/build-n.xml

• latest9.9/userdoc/saxon9/viewer_appJS/xsl/ (jdc-body.xsl, viewer_app.sef.xml)

(But possibly a little more tidying up to do.)

Related to Bug #3988, capture "deprecated" information for dotnetdoc. There is no specific tag in the XML markup for C# documentation comments, but code is marked as deprecated using the "Obsolete" attribute. e.g. [Obsolete("Declare collations globally at the Processor level")] on the XsltCompiler.DeclareCollation() method. The parsecs.xl stylesheet should be updated to capture this information.

Note that the Obsolete attribute content may span multiple lines (e.g. XPathCompiler.DeclareCollation), so some care is needed to get the whole message. i.e. if the line ends with + then need to parse next line (and so on).

Pipeline stylesheets (in build99/MyDotNet/doctools/) updates committed:

• parsecs.xsl - add <obsolete> when starts-with($line, '[Obsolete(')

• merge.xsl - merge <obsolete> elements into the following sibling's comment child

• convert-to-jel-package.xsl - convert <obsolete> elements to <attribute name="@deprecated"> (with div/body content)

• tohtml.xsl - add "Deprecated" info from obsolete elements as required

Further work to handle a generic type class|interface with explicit base; and covariant & contravariant type parameters.

e.g. public interface IXdmEnumerable<out XdmItem> : IEnumerable<XdmItem>

Here the keyword out in <out XdmItem> means IXdmEnumerable has a covariant type parameter; similarly the keyword in is used to declare a contravariant type parameter.

In investigating how we should handle these for the dotnetdoc, I discovered that in fact contravariant type parameters in Java code are not really being handled properly. Covariant types in Java look like e.g. <? extends XdmValue> or <T extends XdmItem>; while contravariant types look like e.g <? super Item>.

The patch for bug #3881 made use of the type/@preamble attribute to provide details about contravariant type parameters (namely the "? super " part of the string). But it would be better to actually add a new attribute type/@super for contravariant types, like the existing type/@extendby used for covariant types.

The jeldoclet has been updated (in classes ClassHandler.java, JavaObject.java, and TypeParts.java) to add this type/@super attribute in the output. (With further tidying in TypeParts.java to do with trimming the values for @fulltype, @type, @extendby, and @super.) Correspondingly, the documentation app stylesheet jdc-body.xsl should then be updated to handle contravariant types from type/@super attributes.

Note that the same jeldoclet is used for generating all versions (9.9, 9.8, etc.) of the javadoc, and contravariant type parameters are only used from Saxon 9.8 for Java. So as well as updating the 9.9 documentation app jdc-body.xsl stylesheet, the 9.8 version should also be updated.

Note that the updates for the 9.9 version of jdc-body.xsl handle the differing syntax for Java and .NET; but for 9.8 we only need to handle the Java syntax (since covariant or contravariant type parameters are only used in Saxon on .NET from 9.9).

Further changes are also made in jdc-body.xsl on the 9.9 branch to tidy up the functions for showing types (add comments; rename f:showMethodType as f:showGenericType; add f:flatGenericType). Furthermore, it includes updates for handling type parameters - with alternative branches for using a paramtypes child if one is found, or otherwise type children (in anticipation of updates for dotnetdoc).

Commits made:

• lib/jeldoclet_1_0/...: ClassHandler.java, JavaObjectType.java, TypeParts.java, jeldoclet.jar
• latest9.9/userdoc/saxon9/viewer_appJS/xsl/jdc-body.xsl (and viewer_app.sef.xml)
• latest9.8/userdoc/saxon9/viewer_app/xsl/jdc-body.xsl

Further updates committed in build99/MyDotNet/doctools/ (convert-to-jel-package.xsl, merge.xsl, parsecs.xsl, tohtml.xsl, + saxon-dotnetdoc.css):

• handle generic type class|interface with explicit base
• tidy up templates & functions used for class|interface inheritance
• handle covariant & contravariant type parameters (use @extendby and @super)
• tidy up use of paramtypes element - now only used for specifying the type parameters for generic methods; for other type parameters, use type children only (note jdc-body.xsl change already committed for this, as referenced in comment above)

Further updates committed in build99/MyDotNet/doctools/ (convert-to-jel-package.xsl, merge.xsl, tohtml.xsl) to fix type warnings and broken type links:

• reorganise resolving of types and use of short names (including System type abbreviations) in pipeline, including use of XPath maps
• update known System types and simplify mechanism for producing System type links
• improve base processing (better handling for lists and generic types)

And latest9.9 viewer app (jdc-body.xsl, viewer_app.xsl, + SEF):

• to fix "Non-Saxon type" warning page mechanism (for javadoc and dotnetdoc)
• simplify mechanism for producing System type links

Further update required for generating the 10 Saxon.Api documentation:

• update the parsecs.xsl stylesheet to handle generic methods with more than one type parameter (e.g. XdmValue.Select)

(Logging here because it is useful to keep the dotnetdoc development information in one place. Change committed under build100.)