Merge pull request #20 from Saxonica/type-parameters

Support type parameters on methods
Saxonica · Oct 4, 2024 · 4c3542b · 4c3542b
2 parents fec1a58 + 812d2b3
commit 4c3542b
Show file tree

Hide file tree

Showing 8 changed files with 110 additions and 10 deletions.
diff --git a/README.md b/README.md
@@ -120,6 +120,12 @@ incomplete or incorrect, please [open an issue](https://github.com/Saxonica/xmld
 
 ## Change log
 
+* **0.13.0** Handle type parameters on methods, renamed a few attributes
+
+    Extended support for type parameters to methods. On several elements, renamed
+    the `type` attribute to `name` for consistency with `fullname`. Updated the
+    schema to be correct wrt the current output.
+
 * **0.12.0** Fix type equality comparison, fix parameterized type purposes
 
     Fixed the issue where the purposes for all params were output for each

diff --git a/gradle.properties b/gradle.properties
@@ -1,4 +1,4 @@
-docletVersion=0.12.0
-schemaVersion=0.12.0
+docletVersion=0.13.0
+schemaVersion=0.13.0
 docletTitle=XmlDoclet
 docletName=xmldoclet
diff --git a/xmldoclet/src/main/java/com/saxonica/xmldoclet/builder/XmlProcessor.java b/xmldoclet/src/main/java/com/saxonica/xmldoclet/builder/XmlProcessor.java
@@ -13,6 +13,7 @@
 
 import javax.lang.model.element.*;
 import javax.lang.model.type.TypeMirror;
+import javax.lang.model.type.TypeVariable;
 import javax.lang.model.util.ElementScanner9;
 import java.io.File;
 import java.io.IOException;
@@ -227,6 +228,9 @@ public void xmlscan(Element element) {
             case PARAMETER:
                 scanner = new XmlParameter(this, (VariableElement) element);
                 break;
+            case TYPE_PARAMETER:
+                scanner = new XmlTypeParameter(this, (TypeParameterElement) element);
+                break;
             case FIELD:
                 scanner = new XmlField(this, (VariableElement) element);
                 break;

diff --git a/xmldoclet/src/main/java/com/saxonica/xmldoclet/scanners/XmlExecutableElement.java b/xmldoclet/src/main/java/com/saxonica/xmldoclet/scanners/XmlExecutableElement.java
@@ -11,7 +11,6 @@
 import javax.lang.model.element.*;
 import javax.lang.model.type.DeclaredType;
 import javax.lang.model.type.TypeMirror;
-import javax.lang.model.util.Types;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -130,6 +129,7 @@ public void scan(DocTree tree) {
        }
 
         builder.xmlscan(element.getParameters());
+        builder.xmlscan(element.getTypeParameters());
 
         if (!"constructor".equals(typeName()) && element.getReturnType() != null) {
             builder.startElement("return");

diff --git a/xmldoclet/src/main/java/com/saxonica/xmldoclet/scanners/XmlTypeElement.java b/xmldoclet/src/main/java/com/saxonica/xmldoclet/scanners/XmlTypeElement.java
@@ -31,7 +31,7 @@ public void scan(DocTree tree) {
         Map<String, String> attr = new HashMap<>();
         attr.put("fullname", element.getQualifiedName().toString());
         attr.put("package", pkgName);
-        attr.put("type", typeName);
+        attr.put("name", typeName);
         attr.put("nesting", element.getNestingKind().toString().toLowerCase());
         attr.putAll(modifierAttributes(element));
 

diff --git a/xmldoclet/src/main/java/com/saxonica/xmldoclet/scanners/XmlTypeParameter.java b/xmldoclet/src/main/java/com/saxonica/xmldoclet/scanners/XmlTypeParameter.java
@@ -0,0 +1,17 @@
+package com.saxonica.xmldoclet.scanners;
+
+import com.saxonica.xmldoclet.builder.XmlProcessor;
+
+import javax.lang.model.element.TypeParameterElement;
+import javax.lang.model.element.VariableElement;
+
+public class XmlTypeParameter extends XmlTypeParameterElement {
+    public XmlTypeParameter(XmlProcessor builder, TypeParameterElement element) {
+        super(builder, element);
+    }
+
+    @Override
+    public String typeName() {
+        return "parameter";
+    }
+}
diff --git a/xmldoclet/src/main/java/com/saxonica/xmldoclet/scanners/XmlTypeParameterElement.java b/xmldoclet/src/main/java/com/saxonica/xmldoclet/scanners/XmlTypeParameterElement.java
@@ -0,0 +1,70 @@
+package com.saxonica.xmldoclet.scanners;
+
+import com.saxonica.xmldoclet.builder.XmlProcessor;
+import com.saxonica.xmldoclet.utils.TypeUtils;
+import com.sun.source.doctree.DocCommentTree;
+import com.sun.source.doctree.DocTree;
+import com.sun.source.doctree.ParamTree;
+
+import javax.lang.model.element.Element;
+import javax.lang.model.element.ElementKind;
+import javax.lang.model.element.TypeParameterElement;
+import javax.lang.model.element.VariableElement;
+import java.util.HashMap;
+import java.util.Map;
+
+public abstract class XmlTypeParameterElement extends XmlScanner {
+    private final TypeParameterElement element;
+
+    public XmlTypeParameterElement(XmlProcessor xmlproc, TypeParameterElement element) {
+        super(xmlproc);
+        this.element = element;
+    }
+
+    public abstract String typeName();
+
+    @Override
+    public void scan(DocTree tree) {
+        Map<String,String> attr = new HashMap<>();
+        attr.put("name", element.getSimpleName().toString());
+        attr.put("class", "type");
+        attr.putAll(modifierAttributes(element));
+
+        builder.startElement(typeName(), attr);
+
+        // If this is a parameter, get the ParamTree block from
+        // our parent...
+        ParamTree paramTree = null;
+        Element parent = element.getEnclosingElement();
+        if (parent.getKind() == ElementKind.METHOD || parent.getKind() == ElementKind.CONSTRUCTOR) {
+            DocCommentTree parentTree = builder.environment.getDocTrees().getDocCommentTree(parent);
+            if (parentTree != null) {
+                for (DocTree block : parentTree.getBlockTags()) {
+                    if (block.getKind() == DocTree.Kind.PARAM) {
+                        ParamTree ptree = (ParamTree) block;
+                        if (ptree.getName().toString().equals(element.getSimpleName().toString())) {
+                            paramTree = ptree;
+                            break;
+                        }
+                    }
+
+                }
+            }
+        }
+
+        if (paramTree != null) {
+            builder.processList("purpose", paramTree.getDescription());
+        }
+
+        if (tree instanceof DocCommentTree) {
+            DocCommentTree dcTree = (DocCommentTree) tree;
+            builder.processList(dcTree.getBlockTags());
+            builder.processList("purpose", dcTree.getFirstSentence());
+            builder.processList("description", dcTree.getBody());
+        }
+
+        TypeUtils.xmlType(builder, "type", element.asType());
+
+        builder.endElement(typeName());
+    }
+}
diff --git a/xmldoclet/src/main/resources/doclet.rnc b/xmldoclet/src/main/resources/doclet.rnc
@@ -91,7 +91,7 @@ class =
         modifiers,
         attribute package { text }?,
         attribute nesting { text },
-        attribute type { text },
+        attribute name { text },
         attribute fullname { text },
         (superclass? & since* & see* & interfaces? & typeparams? & author* & version* & error* & unknown*),
         purpose?,
@@ -110,20 +110,21 @@ interface =
         modifiers,
         attribute package { text }?,
         attribute nesting { text }?,
-        attribute type { text },
+        attribute name { text },
         attribute fullname { text }?,
         (since* & see* & interfaces? & typeparams? & author* & version* & error* & unknown*),
         purpose?,
         description?,
-        (field|method|interface|enum)*
+        param*,
+        (inherited|field|method|interface|enum)*
     }
 
 enum =
     element enum {
         modifiers,
         attribute package { text }?,
         attribute nesting { text }?,
-        attribute type { text },
+        attribute name { text },
         attribute fullname { text }?,
         (superclass? & since* & see* & interfaces? & author* & version* & error* & unknown*),
         purpose?,
@@ -145,6 +146,7 @@ superclass =
         typeDecl,
         inherited?,
         iinterface*,
+        interfaces*,
         superclass?
     }
 
@@ -177,6 +179,7 @@ iinterface =
 interfaces =
     element interfaces {
         interfaceref+
+      | interface+
     }
 
 typeparams =
@@ -186,9 +189,8 @@ typeparams =
 
 typeparam =
     element typeparam {
-        attribute fullname { text }?,
         attribute name { text },
-        empty
+        type, purpose?
     }
 
 field =
@@ -250,6 +252,7 @@ parameter =
     element parameter {
         modifiers,
         attribute name { text },
+        attribute class { "type" }?,
         purpose?,
         description?,
         typeDecl