diff options
Diffstat (limited to 'doclet_adapter/src/main')
61 files changed, 7714 insertions, 0 deletions
diff --git a/doclet_adapter/src/main/java/com/google/doclava/annotation/Unused.java b/doclet_adapter/src/main/java/com/google/doclava/annotation/Unused.java new file mode 100644 index 0000000..f2dbc75 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/annotation/Unused.java @@ -0,0 +1,36 @@ +/* + * Copyright (C) 2022 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.doclava.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Indicates that a method declaration is <b>not required</b> for Doclava to work and <b>does + * not</b> have to be implemented. + * <p> + * The parameter {@code implemented} declares that a method has been implemented, i.e. does not + * throw {@link UnsupportedOperationException} which is used as a default implementation. + */ +@Target(ElementType.METHOD) +@Retention(RetentionPolicy.SOURCE) +public @interface Unused { + + boolean implemented() default false; +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/annotation/Used.java b/doclet_adapter/src/main/java/com/google/doclava/annotation/Used.java new file mode 100644 index 0000000..ac4550c --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/annotation/Used.java @@ -0,0 +1,35 @@ +/* + * Copyright (C) 2022 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.doclava.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Indicates that a method declaration is required for Doclava to work and has to be implemented. + * <p> + * The parameter {@code implemented} declares that a method has been implemented, i.e. does not + * throw {@link UnsupportedOperationException} which is used as a default implementation. + */ +@Target(ElementType.METHOD) +@Retention(RetentionPolicy.SOURCE) +public @interface Used { + + boolean implemented() default false; +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotatedTypeImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotatedTypeImpl.java new file mode 100644 index 0000000..17dc78a --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotatedTypeImpl.java @@ -0,0 +1,77 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotatedType; +import com.sun.javadoc.AnnotationDesc; +import com.sun.javadoc.Type; +import javax.lang.model.type.DeclaredType; + +class AnnotatedTypeImpl extends TypeImpl implements AnnotatedType { + + private final DeclaredType declaredType; + + private Type underlyingType; + + private AnnotationDesc[] annotations; + + protected AnnotatedTypeImpl(DeclaredType declaredType, Context context) { + super(declaredType, context); + this.declaredType = declaredType; + } + + static AnnotatedTypeImpl create(DeclaredType declaredType, Context context) { + return context.caches.types.annotated.computeIfAbsent(declaredType, + el -> new AnnotatedTypeImpl(el, context)); + } + + /** + * @return annotations + * @implNote Implemented as used in {@code ParameterImplTests#annotations()}. + */ + @Override + @Unused(implemented = true) + public AnnotationDesc[] annotations() { + if (annotations == null) { + annotations = declaredType.getAnnotationMirrors() + .stream() + .map(am -> new AnnotationDescImpl(am, context)) + .toArray(AnnotationDescImpl[]::new); + } + return annotations; + } + + @Override + @Used(implemented = true) + public Type underlyingType() { + if (underlyingType == null) { + underlyingType = TypeImpl.create(declaredType, context); + } + return underlyingType; + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationDescImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationDescImpl.java new file mode 100644 index 0000000..dcb8695 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationDescImpl.java @@ -0,0 +1,96 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotationDesc; +import com.sun.javadoc.AnnotationTypeDoc; +import com.sun.javadoc.AnnotationTypeElementDoc; +import com.sun.javadoc.AnnotationValue; +import javax.lang.model.element.AnnotationMirror; +import javax.lang.model.element.TypeElement; + +class AnnotationDescImpl implements AnnotationDesc { + + private final AnnotationTypeDocImpl annotationType; + private final ElementValuePairImpl[] elementValues; + + public AnnotationDescImpl(AnnotationMirror mirror, Context context) { + this.annotationType = AnnotationTypeDocImpl.create( + (TypeElement) mirror.getAnnotationType().asElement(), context); + this.elementValues = mirror.getElementValues() + .entrySet() + .stream() + .map(kv -> { + var element = AnnotationMethodDocImpl.create(kv.getKey(), context); + var value = AnnotationValueImpl.create(kv.getValue(), context); + return new ElementValuePairImpl(element, value); + }) + .toArray(ElementValuePairImpl[]::new); + } + + @Override + @Used(implemented = true) + public AnnotationTypeDoc annotationType() { + return annotationType; + } + + @Override + @Used(implemented = true) + public ElementValuePair[] elementValues() { + return elementValues; + } + + @Override + @Unused + public boolean isSynthesized() { + throw new UnsupportedOperationException("not yet implemented"); + } + + static class ElementValuePairImpl implements ElementValuePair { + + private final AnnotationMethodDocImpl element; + private final AnnotationValueImpl value; + + public ElementValuePairImpl(AnnotationMethodDocImpl element, AnnotationValueImpl value) { + this.element = element; + this.value = value; + } + + @Override + @Used(implemented = true) + public AnnotationTypeElementDoc element() { + return element; + } + + @Override + @Used(implemented = true) + public AnnotationValue value() { + return value; + } + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationMethodDocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationMethodDocImpl.java new file mode 100644 index 0000000..8e3813c --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationMethodDocImpl.java @@ -0,0 +1,73 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotationTypeElementDoc; +import com.sun.javadoc.AnnotationValue; +import javax.lang.model.element.ExecutableElement; + +/** + * In a nutshell, represents a method of an annotation. + */ +class AnnotationMethodDocImpl extends MethodDocImpl implements AnnotationTypeElementDoc { + + protected AnnotationValueImpl defaultValue; + + protected AnnotationMethodDocImpl(ExecutableElement e, Context context) { + super(e, context); + defaultValue = AnnotationValueImpl.create(e.getDefaultValue(), context); + } + + static AnnotationMethodDocImpl create(ExecutableElement e, Context context) { + return context.caches.annotationMethods.computeIfAbsent(e, + el -> new AnnotationMethodDocImpl(el, context)); + } + + @Override + @Used(implemented = true) + public AnnotationValue defaultValue() { + return defaultValue; + } + + @Override + @Used(implemented = true) + public boolean isAnnotationTypeElement() { + return true; + } + + @Override + @Used(implemented = true) + public boolean isMethod() { + return false; + } + + @Override + @Used(implemented = true) + public boolean isAbstract() { + return false; + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationTypeDocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationTypeDocImpl.java new file mode 100644 index 0000000..58bfdfe --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationTypeDocImpl.java @@ -0,0 +1,83 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotationTypeDoc; +import com.sun.javadoc.AnnotationTypeElementDoc; +import javax.lang.model.element.ElementKind; +import javax.lang.model.element.TypeElement; +import javax.lang.model.util.ElementFilter; + +class AnnotationTypeDocImpl extends ClassDocImpl implements AnnotationTypeDoc { + + protected AnnotationTypeDocImpl(TypeElement c, Context context) { + super(c, context); + } + + // Cached fields + private AnnotationTypeElementDoc[] elements; + + static AnnotationTypeDocImpl create(TypeElement e, Context context) { + if (e.getKind() != ElementKind.ANNOTATION_TYPE) { + throw new IllegalArgumentException("Expected ElementKind.ANNOTATION_TYPE as first " + + "argument, but got " + e.getKind()); + } + return context.caches.annotations.computeIfAbsent(e, el -> new AnnotationTypeDocImpl(el, + context)); + } + + @Override + @Used(implemented = true) + public AnnotationTypeElementDoc[] elements() { + if (elements == null) { + elements = ElementFilter.methodsIn(typeElement.getEnclosedElements()) + .stream() + .map(exe -> AnnotationMethodDocImpl.create(exe, context)) + .toArray(AnnotationTypeElementDoc[]::new); + } + return elements; + } + + @Override + @Used(implemented = true) + public boolean isAnnotationType() { + return true; + } + + @Override + @Used(implemented = true) + public boolean isInterface() { + return false; + } + + @Override + @Unused(implemented = true) + public AnnotationTypeDoc asAnnotationTypeDoc() { + return this; + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationValueImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationValueImpl.java new file mode 100644 index 0000000..e3ea5d0 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/AnnotationValueImpl.java @@ -0,0 +1,156 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotationValue; +import java.util.List; +import javax.annotation.Nonnull; +import javax.annotation.Nullable; +import javax.lang.model.element.AnnotationMirror; +import javax.lang.model.element.TypeElement; +import javax.lang.model.element.VariableElement; +import javax.lang.model.type.TypeMirror; +import javax.lang.model.util.SimpleAnnotationValueVisitor14; + +class AnnotationValueImpl implements AnnotationValue { + + protected final javax.lang.model.element.AnnotationValue annotationValue; + protected final Context context; + + protected AnnotationValueImpl(@Nonnull javax.lang.model.element.AnnotationValue av, + Context context) { + this.context = context; + annotationValue = av; + } + + public static @Nullable + AnnotationValueImpl create(@Nullable javax.lang.model.element.AnnotationValue av, + Context context) { + // av could be null if it's a result of ExecutableElement#getDefaultValue() + if (av == null) { + return null; + } + return context.caches.annotationValues.computeIfAbsent(av, + el -> new AnnotationValueImpl(el, context)); + } + + private Object value; + + @Override + @Used(implemented = true) + public Object value() { + if (value == null) { + value = valueVisitor.visit(annotationValue, context); + } + return value; + } + + private static final SimpleAnnotationValueVisitor14<Object, Context> valueVisitor = + new SimpleAnnotationValueVisitor14<>() { + @Override + public Object visitBoolean(boolean b, Context ctx) { + return b; + } + + @Override + public Object visitByte(byte b, Context ctx) { + return b; + } + + @Override + public Object visitChar(char c, Context ctx) { + return c; + } + + @Override + public Object visitDouble(double d, Context ctx) { + return d; + } + + @Override + public Object visitFloat(float f, Context ctx) { + return f; + } + + @Override + public Object visitInt(int i, Context ctx) { + return i; + } + + @Override + public Object visitLong(long l, Context ctx) { + return l; + } + + @Override + public Object visitShort(short s, Context ctx) { + return s; + } + + @Override + public Object visitString(String s, Context ctx) { + return s; + } + + @Override + public Object visitType(TypeMirror m, Context ctx) { + var e = ctx.environment.getTypeUtils().asElement(m); + return switch (e.getKind()) { + case CLASS, INTERFACE, ENUM -> ClassDocImpl.create((TypeElement) e, ctx); + case ANNOTATION_TYPE -> AnnotationTypeDocImpl.create((TypeElement) e, ctx); + default -> throw new UnsupportedOperationException( + e.getKind() + " is not not yet implemented"); + }; + } + + @Override + public Object visitEnumConstant(VariableElement c, Context context) { + return null; + } + + @Override + public Object visitAnnotation(AnnotationMirror m, Context ctx) { + return null; + } + + @Override + public Object visitArray( + List<? extends javax.lang.model.element.AnnotationValue> vals, + Context ctx) { + AnnotationValueImpl[] ret = new AnnotationValueImpl[vals.size()]; + for (int i = 0; i < vals.size(); i++) { + ret[i] = AnnotationValueImpl.create(vals.get(i), ctx); + } + return ret; + } + + @Override + protected Object defaultAction(Object o, Context context) { + throw new UnsupportedOperationException("Unexpected annotation value: " + o); + } + }; +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/ArrayTypeImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ArrayTypeImpl.java new file mode 100644 index 0000000..b7ba0a1 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ArrayTypeImpl.java @@ -0,0 +1,110 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotationTypeDoc; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.ParameterizedType; +import com.sun.javadoc.Type; +import com.sun.javadoc.TypeVariable; +import javax.lang.model.type.ArrayType; +import javax.lang.model.type.TypeKind; +import javax.lang.model.type.TypeMirror; + +public final class ArrayTypeImpl extends TypeImpl { + + private final ArrayType arrayType; + private final Type underlyingType; + private final String dimension; + + private ArrayTypeImpl(ArrayType at, Context context) { + super(at, context); + arrayType = at; + + int dim = 0; + TypeMirror cur = at; + while (cur.getKind() == TypeKind.ARRAY) { + dim++; + cur = ((ArrayType) cur).getComponentType(); + } + dimension = "[]".repeat(dim); + underlyingType = TypeImpl.create(cur, context); + } + + public static ArrayTypeImpl create(ArrayType at, Context context) { + return context.caches.types.array.computeIfAbsent(at, x -> new ArrayTypeImpl(x, context)); + } + + @Override + @Used(implemented = true) + public String qualifiedTypeName() { + return underlyingType.qualifiedTypeName(); + } + + @Override + @Used(implemented = true) + public String simpleTypeName() { + return underlyingType.simpleTypeName(); + } + + @Override + @Used(implemented = true) + public String dimension() { + return dimension; + } + + @Override + @Used(implemented = true) + public ClassDoc asClassDoc() { + return underlyingType.asClassDoc(); + } + + @Override + @Used(implemented = true) + public TypeVariable asTypeVariable() { + return underlyingType.asTypeVariable(); + } + + @Override + @Used(implemented = true) + public ParameterizedType asParameterizedType() { + return underlyingType.asParameterizedType(); + } + + @Override + @Unused(implemented = true) + public AnnotationTypeDoc asAnnotationTypeDoc() { + return underlyingType.asAnnotationTypeDoc(); + } + + @Override + @Used(implemented = true) + public boolean isPrimitive() { + return underlyingType.isPrimitive(); + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/ClassDocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ClassDocImpl.java new file mode 100644 index 0000000..8bd6d5e --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ClassDocImpl.java @@ -0,0 +1,631 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotatedType; +import com.sun.javadoc.AnnotationTypeDoc; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.ConstructorDoc; +import com.sun.javadoc.FieldDoc; +import com.sun.javadoc.MethodDoc; +import com.sun.javadoc.PackageDoc; +import com.sun.javadoc.ParamTag; +import com.sun.javadoc.ParameterizedType; +import com.sun.javadoc.Type; +import com.sun.javadoc.TypeVariable; +import com.sun.javadoc.WildcardType; +import javax.lang.model.element.ElementKind; +import javax.lang.model.element.ExecutableElement; +import javax.lang.model.element.NestingKind; +import javax.lang.model.element.TypeElement; +import javax.lang.model.element.VariableElement; +import javax.lang.model.type.TypeKind; +import javax.lang.model.type.TypeMirror; +import javax.lang.model.util.ElementFilter; + +class ClassDocImpl extends ProgramElementDocImpl<TypeElement> implements ClassDoc { + + protected final TypeElement typeElement; + + // Cached fields + private ConstructorDoc[] constructorsFiltered; + private ConstructorDoc[] constructorsAll; + private Type[] interfaceTypes; + private ClassDoc[] interfaces; + private TypeVariable[] typeParameters; + private MethodDoc[] methodsFiltered; + private MethodDoc[] methodsAll; + private FieldDoc[] fieldsFiltered; + private FieldDoc[] fieldsAll; + private FieldDoc[] enumConstants; + private ClassDoc[] innerClassesFiltered; + private ClassDoc[] innerClassesAll; + + protected ClassDocImpl(TypeElement c, Context context) { + super(c, context); + typeElement = c; + + if (c.getKind().isInterface()) { + reflectModifiers |= java.lang.reflect.Modifier.INTERFACE; + } + } + + static ClassDocImpl create(TypeElement e, Context context) { + return context.caches.classes.computeIfAbsent(e, el -> new ClassDocImpl(el, context)); + } + + @Override + @Unused(implemented = true) + public String modifiers() { + return java.lang.reflect.Modifier.toString(modifierSpecifier()); + } + + @Override + @Unused(implemented = true) + public int modifierSpecifier() { + if (isInterface() || isAnnotationType()) { + return reflectModifiers & ~java.lang.reflect.Modifier.ABSTRACT; + } + return reflectModifiers; + } + + private Boolean isClass; + + @Override + @Unused(implemented = true) + public boolean isClass() { + if (isClass == null) { + isClass = typeElement.getKind().isClass(); + } + return isClass; + } + + private Boolean isOrdinaryClass; + + @Override + @Used(implemented = true) + public boolean isOrdinaryClass() { + if (isOrdinaryClass == null) { + isOrdinaryClass = (!isEnum() && + !isInterface() && + !isAnnotationType() && + !isError() && + !isException() + ); + } + return isOrdinaryClass; + } + + private Boolean isEnum; + + @Override + @Used(implemented = true) + public boolean isEnum() { + if (isEnum == null) { + isEnum = (typeElement.getKind() == ElementKind.ENUM); + } + return isEnum; + } + + private Boolean isInterface; + + @Override + @Used(implemented = true) + public boolean isInterface() { + if (isInterface == null) { + isInterface = (typeElement.getKind() == ElementKind.INTERFACE); + } + return isInterface; + } + + private Boolean isException; + + @Override + @Used(implemented = true) + public boolean isException() { + if (isException == null) { + isException = context.docletElementUtils.isException(typeElement); + } + return isException; + } + + private Boolean isError; + + @Override + @Used(implemented = true) + public boolean isError() { + if (isError == null) { + isError = context.docletElementUtils.isError(typeElement); + } + return isError; + } + + private String name; + + @Override + @Used(implemented = true) + public String name() { + if (name == null) { + name = context.docletElementUtils.getClassNameUntilNotNested(typeElement); + } + return name; + } + + private String qualifiedName; + + @Override + @Used(implemented = true) + public String qualifiedName() { + if (qualifiedName == null) { + qualifiedName = typeElement.getQualifiedName().toString(); + } + return qualifiedName; + } + + @Override + @Used(implemented = true) + public boolean isIncluded() { + return context.environment.isIncluded(typeElement); + } + + @Override + @Used(implemented = true) + public boolean isAbstract() { + return java.lang.reflect.Modifier.isAbstract(reflectModifiers); + } + + private Boolean isSerializable; + + @Override + @Used(implemented = true) + public boolean isSerializable() { + if (isSerializable == null) { + var serializable = context.environment.getElementUtils() + .getTypeElement("java.io.Serializable").asType(); + isSerializable = context.environment.getTypeUtils() + .isSubtype(typeElement.asType(), serializable); + } + return isSerializable; + } + + private Boolean isExternalizable; + + @Override + @Unused(implemented = true) + public boolean isExternalizable() { + if (isExternalizable == null) { + var externalizable = context.environment.getElementUtils() + .getTypeElement("java.io.Externalizable").asType(); + isExternalizable = context.environment.getTypeUtils() + .isSubtype(typeElement.asType(), externalizable); + } + return isExternalizable; + } + + @Override + @Unused + public MethodDoc[] serializationMethods() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public FieldDoc[] serializableFields() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public boolean definesSerializableFields() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public ClassDoc superclass() { + if (isInterface()) { + return null; + } + TypeMirror superclassMirror = typeElement.getSuperclass(); + if (superclassMirror.getKind() == TypeKind.NONE) { + return null; + } + Type t = TypeImpl.create(superclassMirror, context); + if (t instanceof ClassDoc cls) { + return cls; + } else { + return null; + } + } + + @Override + @Used(implemented = true) + public Type superclassType() { + if (isInterface()) { + return null; + } + TypeMirror superclassMirror = typeElement.getSuperclass(); + if (superclassMirror.getKind() == TypeKind.NONE) { + return null; + } + Type t = TypeImpl.create(superclassMirror, context); + if (t instanceof ClassDoc cls) { + return cls; + } else if (t instanceof ParameterizedType pt) { + return pt; + } else { + return null; + } + } + + @Override + @Unused(implemented = true) + public boolean subclassOf(ClassDoc cd) { + TypeElement other = context.environment.getElementUtils() + .getTypeElement(cd.qualifiedName()); + if (isInterface()) { + return other.getQualifiedName().contentEquals("java.lang.Object"); + } + return context.environment.getTypeUtils().isSubtype(typeElement.asType(), other.asType()); + } + + @Override + @Used(implemented = true) + public ClassDoc[] interfaces() { + if (interfaces == null) { + interfaces = typeElement.getInterfaces() + .stream() + .map(typeMirror -> { + TypeElement asElement = (TypeElement) context.environment.getTypeUtils() + .asElement(typeMirror); + return ClassDocImpl.create(asElement, context); + }) + .toArray(ClassDoc[]::new); + } + return interfaces; + } + + @Override + @Used(implemented = true) + public Type[] interfaceTypes() { + return interfaces(); + } + + @Override + @Used(implemented = true) + public TypeVariable[] typeParameters() { + if (typeParameters == null) { + typeParameters = typeElement.getTypeParameters() + .stream() + .map(tp -> { + javax.lang.model.type.TypeVariable tv = (javax.lang.model.type.TypeVariable) tp.asType(); + return TypeVariableImpl.create(tv, context); + }) + .toArray(TypeVariable[]::new); + } + return typeParameters; + } + + @Override + @Unused + public ParamTag[] typeParamTags() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused(implemented = true) + public FieldDoc[] fields() { + if (fieldsAll == null) { + fieldsAll = getFields(true); + } + return fieldsAll; + } + + @Override + @Used(implemented = true) + public FieldDoc[] fields(boolean filter) { + if (filter) { + if (fieldsFiltered == null) { + fieldsFiltered = getFields(true); + } + return fieldsFiltered; + } else { + if (fieldsAll == null) { + fieldsAll = getFields(false); + } + return fieldsAll; + } + } + + private FieldDoc[] getFields(boolean filter) { + return typeElement.getEnclosedElements() + .stream() + .filter(e -> e.getKind() == ElementKind.FIELD) + .filter(field -> !filter || context.environment.isSelected(field)) + .map(field -> FieldDocImpl.create((VariableElement) field, context)) + .toArray(FieldDoc[]::new); + } + + @Override + @Used(implemented = true) + public FieldDoc[] enumConstants() { + if (enumConstants == null) { + enumConstants = typeElement.getEnclosedElements() + .stream() + .filter(e -> e.getKind() == ElementKind.ENUM_CONSTANT) + .map(enumConstant -> FieldDocImpl.create((VariableElement) enumConstant, + context)) + .toArray(FieldDoc[]::new); + } + return enumConstants; + } + + @Override + @Unused(implemented = true) + public MethodDoc[] methods() { + if (methodsAll == null) { + methodsAll = getMethods(true); + } + return methodsAll; + } + + @Override + @Used(implemented = true) + public MethodDoc[] methods(boolean filter) { + if (filter) { + if (methodsFiltered == null) { + methodsFiltered = getMethods(true); + } + return methodsFiltered; + } else { + if (methodsAll == null) { + methodsAll = getMethods(false); + } + return methodsAll; + } + } + + private MethodDoc[] getMethods(boolean filter) { + return typeElement.getEnclosedElements() + .stream() + .filter(e -> e.getKind() == ElementKind.METHOD) + .filter(method -> !filter || context.environment.isSelected(method)) + .map(method -> MethodDocImpl.create((ExecutableElement) method, context)) + .toArray(MethodDoc[]::new); + } + + @Override + @Unused(implemented = true) + public ConstructorDoc[] constructors() { + if (constructorsFiltered == null) { + constructorsFiltered = getConstructors(true); + } + return constructorsFiltered; + } + + @Override + @Used(implemented = true) + public ConstructorDoc[] constructors(boolean filter) { + if (filter) { + if (constructorsFiltered == null) { + constructorsFiltered = getConstructors(true); + } + return constructorsFiltered; + } else { + if (constructorsAll == null) { + constructorsAll = getConstructors(false); + } + return constructorsAll; + } + } + + private ConstructorDoc[] getConstructors(boolean filter) { + return typeElement.getEnclosedElements() + .stream() + .filter(e -> e.getKind() == ElementKind.CONSTRUCTOR) + .filter(ctor -> !filter || context.environment.isSelected(ctor)) + .map(e -> ConstructorDocImpl.create((ExecutableElement) e, context)) + .toArray(ConstructorDoc[]::new); + } + + @Override + @Used(implemented = true) + public ClassDoc[] innerClasses() { + if (innerClassesFiltered == null) { + innerClassesFiltered = getInnerClasses(true); + } + return innerClassesFiltered; + } + + @Override + @Used(implemented = true) + public ClassDoc[] innerClasses(boolean filter) { + if (filter) { + return innerClasses(); + } else { + if (innerClassesAll == null) { + innerClassesAll = getInnerClasses(false); + } + return innerClassesAll; + } + } + + private ClassDoc[] getInnerClasses(boolean filter) { + return ElementFilter.typesIn(typeElement.getEnclosedElements()) + .stream() + .filter(te -> te.getNestingKind() == NestingKind.MEMBER && + (te.getKind() == ElementKind.CLASS || te.getKind() == ElementKind.INTERFACE) + ) + .filter(te -> !filter || context.environment.isSelected(te)) + .map(te -> ClassDocImpl.create(te, context)) + .toArray(ClassDoc[]::new); + } + + /** + * Note that this implementation does not search in sources! + * + * <p> + * + * {@inheritDoc} + * + * @implNote Does not search in sources. + */ + @Override + @Used(implemented = true) + public ClassDoc findClass(String className) { + ClassDoc result = searchClass(className); + if (result != null) { + return result; + } + + ClassDoc enclosing = containingClass(); + while (enclosing != null && enclosing.containingClass() != null) { + enclosing = enclosing.containingClass(); + } + if (enclosing == null) { + return null; + } + return ((ClassDocImpl) enclosing).searchClass(className); + } + + private ClassDoc searchClass(String className) { + TypeElement cls = context.environment.getElementUtils().getTypeElement(className); + if (cls != null) { + return ClassDocImpl.create(cls, context); + } + + for (ClassDoc nested : innerClasses()) { + if (nested.name().equals(className) || nested.name().endsWith("." + className)) { + return nested; + } else { + ClassDoc inNested = ((ClassDocImpl) nested).searchClass(className); + if (inNested != null) { + return inNested; + } + } + } + + ClassDoc inPackage = containingPackage().findClass(className); + if (inPackage != null) { + return inPackage; + } + + // + + return null; + } + + @Override + @Unused + public ClassDoc[] importedClasses() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public PackageDoc[] importedPackages() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused(implemented = true) + public String typeName() { + return name(); + } + + @Override + @Used(implemented = true) + public String qualifiedTypeName() { + return qualifiedName(); + } + + private String simpleTypeName; + + @Override + @Used(implemented = true) + public String simpleTypeName() { + if (simpleTypeName == null) { + simpleTypeName = typeElement.getSimpleName().toString(); + } + return simpleTypeName; + } + + @Override + @Used(implemented = true) + public String dimension() { + return ""; + } + + @Override + @Used(implemented = true) + public boolean isPrimitive() { + return false; + } + + @Override + @Used(implemented = true) + public ClassDoc asClassDoc() { + return this; + } + + @Override + @Used(implemented = true) + public ParameterizedType asParameterizedType() { + return null; + } + + @Override + @Used(implemented = true) + public TypeVariable asTypeVariable() { + return null; + } + + @Override + @Used(implemented = true) + public WildcardType asWildcardType() { + return null; + } + + @Override + @Used(implemented = true) + public AnnotatedType asAnnotatedType() { + return null; + } + + @Override + @Unused(implemented = true) + public AnnotationTypeDoc asAnnotationTypeDoc() { + return null; + } + + @Override + @Used(implemented = true) + public Type getElementType() { + return null; + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/ConstructorDocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ConstructorDocImpl.java new file mode 100644 index 0000000..324cb98 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ConstructorDocImpl.java @@ -0,0 +1,69 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.ConstructorDoc; +import javax.lang.model.element.ExecutableElement; +import javax.lang.model.element.TypeElement; + +class ConstructorDocImpl extends ExecutableMemberDocImpl implements ConstructorDoc { + + protected ConstructorDocImpl(ExecutableElement e, Context context) { + super(e, context); + } + + static ConstructorDocImpl create(ExecutableElement e, Context context) { + return context.caches.constructors.computeIfAbsent(e, + el -> new ConstructorDocImpl(el, context)); + } + + @Override + @Unused(implemented = true) + public boolean isConstructor() { + return true; + } + + @Override + @Used(implemented = true) + public String name() { + return executableElement.getEnclosingElement().getSimpleName().toString(); + } + + @Override + @Used(implemented = true) + public String qualifiedName() { + var enclosingClass = executableElement.getEnclosingElement(); + return switch (enclosingClass.getKind()) { + case CLASS, INTERFACE, ANNOTATION_TYPE, ENUM -> + ((TypeElement) enclosingClass).getQualifiedName().toString(); + default -> throw new UnsupportedOperationException("Expected CLASS, INTERFACE, " + + "ANNOTATION_TYPE or ENUM, but got " + enclosingClass.getKind()); + }; + } + +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/Context.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/Context.java new file mode 100644 index 0000000..cfa3bb8 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/Context.java @@ -0,0 +1,118 @@ +/* + * Copyright (C) 2022 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.doclava.javadoc; + +import com.sun.javadoc.Doc; +import com.sun.source.doctree.DocTree; +import com.sun.source.doctree.ParamTree; +import com.sun.source.doctree.SeeTree; +import com.sun.source.doctree.SerialFieldTree; +import com.sun.source.doctree.ThrowsTree; +import java.util.HashMap; +import java.util.Map; +import javax.lang.model.element.AnnotationValue; +import javax.lang.model.element.Element; +import javax.lang.model.element.ExecutableElement; +import javax.lang.model.element.PackageElement; +import javax.lang.model.element.TypeElement; +import javax.lang.model.element.VariableElement; +import javax.lang.model.type.ArrayType; +import javax.lang.model.type.DeclaredType; +import javax.lang.model.type.TypeMirror; +import javax.lang.model.type.TypeVariable; +import javax.lang.model.type.WildcardType; +import javax.lang.model.util.SimpleElementVisitor14; +import jdk.javadoc.doclet.DocletEnvironment; + +/** + * Holds temporary objects required to construct {@link RootDocImpl} from a {@link + * jdk.javadoc.doclet.DocletEnvironment}. + */ +class Context { + + public final DocletEnvironment environment; + public final Caches caches = new Caches(); + public final DocletElementUtils docletElementUtils; + + public Doc obtain(Element element) { + return OBTAIN_VISITOR.visit(element, this); + } + + public static class Caches { + + public final Map<TypeElement, ClassDocImpl> classes = new HashMap<>(); + public final Map<TypeElement, AnnotationTypeDocImpl> annotations = new HashMap<>(); + public final Map<PackageElement, PackageDocImpl> packages = new HashMap<>(); + public final Map<ExecutableElement, AnnotationMethodDocImpl> annotationMethods = + new HashMap<>(); + public final Map<AnnotationValue, AnnotationValueImpl> annotationValues = new HashMap<>(); + public final Map<ExecutableElement, ConstructorDocImpl> constructors = new HashMap<>(); + public final Map<ExecutableElement, MethodDocImpl> methods = new HashMap<>(); + public final Map<VariableElement, FieldDocImpl> fields = new HashMap<>(); + public final Map<VariableElement, ParameterImpl> parameters = new HashMap<>(); + + public final Tags tags = new Tags(); + public final Types types = new Types(); + + public static class Tags { + + public final Map<Element, Map<DocTree, TagImpl>> generic = new HashMap<>(); + public final Map<Element, Map<SeeTree, SeeTagImpl>> see = new HashMap<>(); + public final Map<Element, Map<SerialFieldTree, SerialFieldTagImpl>> serialField = + new HashMap<>(); + public final Map<Element, Map<ParamTree, ParamTagImpl>> param = new HashMap<>(); + public final Map<Element, Map<ThrowsTree, ThrowsTagImpl>> throwz = new HashMap<>(); + } + + public static class Types { + + public final Map<TypeMirror, TypeImpl> common = new HashMap<>(); + public final Map<DeclaredType, AnnotatedTypeImpl> annotated = new HashMap<DeclaredType, AnnotatedTypeImpl>(); + public final Map<WildcardType, WildcardTypeImpl> wildcard = new HashMap<>(); + public final Map<DeclaredType, ParameterizedTypeImpl> parameterized = new HashMap<>(); + public final Map<TypeVariable, TypeVariableImpl> typevar = new HashMap<>(); + public final Map<ArrayType, ArrayTypeImpl> array = new HashMap<>(); + } + } + + public Context(DocletEnvironment environment) { + this.environment = environment; + this.docletElementUtils = new DocletElementUtils(environment); + } + + private static final SimpleElementVisitor14<Doc, Context> OBTAIN_VISITOR = + new SimpleElementVisitor14<>() { + + @Override + public Doc visitPackage(PackageElement e, Context context) { + return PackageDocImpl.create(e, context); + } + + @Override + public Doc visitType(TypeElement e, Context context) { + return switch (e.getKind()) { + case CLASS, ENUM, INTERFACE -> ClassDocImpl.create(e, context); + case ANNOTATION_TYPE -> AnnotationTypeDocImpl.create(e, context); + case RECORD -> throw new UnsupportedOperationException( + "Records not yet supported"); + default -> throw new IllegalArgumentException( + "Expected ANNOTATION_TYPE, CLASS, " + + "ENUM, INTERFACE, or RECORD; but got " + e.getKind()); + }; + } + }; +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/DocErrorReporterImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/DocErrorReporterImpl.java new file mode 100644 index 0000000..6687365 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/DocErrorReporterImpl.java @@ -0,0 +1,111 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.sun.javadoc.DocErrorReporter; +import com.sun.javadoc.SourcePosition; + +class DocErrorReporterImpl implements DocErrorReporter { + + /** + * Print error message and increment error count. + * + * @param msg message to print + */ + @Override + @Unused + public void printError(String msg) { + throw new UnsupportedOperationException("not yet implemented"); + // TODO(nikitai): implement this printError(...). + } + + /** + * Print an error message and increment error count. + * + * @param pos the position item where the error occurs + * @param msg message to print + * @since 1.4 + */ + @Override + @Unused + public void printError(SourcePosition pos, String msg) { + throw new UnsupportedOperationException("not yet implemented"); + // TODO(nikitai): implement this printError(...). + } + + /** + * Print warning message and increment warning count. + * + * @param msg message to print + */ + @Override + @Unused + public void printWarning(String msg) { + throw new UnsupportedOperationException("not yet implemented"); + // TODO(nikitai): implement this printWarning(...). + } + + /** + * Print warning message and increment warning count. + * + * @param pos the position item where the warning occurs + * @param msg message to print + * @since 1.4 + */ + @Override + @Unused + public void printWarning(SourcePosition pos, String msg) { + throw new UnsupportedOperationException("not yet implemented"); + // TODO(nikitai): implement this printWarning(...). + } + + /** + * Print a message. + * + * @param msg message to print + */ + @Override + @Unused + public void printNotice(String msg) { + throw new UnsupportedOperationException("not yet implemented"); + // TODO(nikitai): implement this printNotice(...). + } + + /** + * Print a message. + * + * @param pos the position item where the message occurs + * @param msg message to print + * @since 1.4 + */ + @Override + @Unused + public void printNotice(SourcePosition pos, String msg) { + throw new UnsupportedOperationException("not yet implemented"); + // TODO(nikitai): implement this printNotice(...). + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/DocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/DocImpl.java new file mode 100644 index 0000000..0ad7c6f --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/DocImpl.java @@ -0,0 +1,264 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.Doc; +import com.sun.javadoc.SeeTag; +import com.sun.javadoc.SourcePosition; +import com.sun.javadoc.Tag; +import com.sun.source.doctree.DocCommentTree; +import com.sun.source.doctree.DocTree; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.stream.Collectors; +import javax.lang.model.element.Element; + +abstract class DocImpl<T extends Element> implements Doc, Comparable<Object> { + + protected final T element; + protected final Context context; + + protected DocImpl(T e, Context context) { + this.element = e; + this.context = context; + } + + private String commentText; + + @Override + @Unused(implemented = true) + public String commentText() { + if (commentText == null) { + var dt = context.environment.getDocTrees().getDocCommentTree(element); + commentText = dt.getFullBody().stream() + .map(DocTree::toString) + .collect(Collectors.joining()) + .trim(); + } + return commentText; + } + + private Tag[] tags; + + @Override + @Unused(implemented = true) + public Tag[] tags() { + if (tags == null) { + DocCommentTree tree = context.environment.getDocTrees().getDocCommentTree(element); + List<? extends DocTree> blockTags = tree.getBlockTags(); + + tags = blockTags + .stream() + .map(docTree -> TagImpl.create(docTree, element, context)) + .toArray(Tag[]::new); + } + return tags; + } + + @Override + @Unused(implemented = true) + public Tag[] tags(String kind) { + return Arrays.stream(tags()) + .filter(t -> t.kind().equals(kind)) + .toArray(Tag[]::new); + } + + private SeeTag[] seeTags; + + @Override + @Unused(implemented = true) + public SeeTag[] seeTags() { + if (seeTags == null) { + seeTags = Arrays.stream(tags()) + .filter(t -> t instanceof SeeTagImpl) + .toArray(SeeTag[]::new); + } + return seeTags; + } + + private Tag[] inlineTags; + + @Override + @Used(implemented = true) + public Tag[] inlineTags() { + if (inlineTags == null) { + var dt = context.environment.getDocTrees().getDocCommentTree(element); + if (dt == null) { + inlineTags = new Tag[0]; + } else { + List<DocTree> tags = new ArrayList<>(dt.getFullBody()); + inlineTags = tags.stream() + .map(tag -> TagImpl.create(tag, element, context)) + .toArray(Tag[]::new); + } + } + return inlineTags; + } + + private Tag[] firstSentenceTags; + + @Override + @Unused(implemented = true) + public Tag[] firstSentenceTags() { + if (firstSentenceTags == null) { + var dt = context.environment.getDocTrees().getDocCommentTree(element); + firstSentenceTags = dt.getFirstSentence().stream() + .map(tag -> TagImpl.create(tag, element, context)) + .toArray(Tag[]::new); + } + return firstSentenceTags; + } + + private String getRawCommentText; + + /** + * {@inheritDoc} + * + * @implNote this implementation prettifies javadoc a bit; previous implementation returned + * javadoc as-is without any modifications. + * + */ + @Override + @Used(implemented = true) + public String getRawCommentText() { + if (getRawCommentText == null) { + var dt = context.environment.getDocTrees().getDocCommentTree(element); + if (dt == null) { + getRawCommentText = ""; + } else { + //TODO: this implementation is slightly different, consider reimplementing. + getRawCommentText = dt.toString(); + } + } + return getRawCommentText; + } + + @Override + @Unused + public void setRawCommentText(String rawDocumentation) { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public String toString() { + return qualifiedName(); + } + + @Override + public abstract String name(); + + public abstract String qualifiedName(); + + @Override + public int compareTo(Object obj) { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused(implemented = true) + public boolean isField() { + return false; + } + + @Override + @Unused(implemented = true) + public boolean isEnumConstant() { + return false; + } + + @Override + @Unused(implemented = true) + public boolean isConstructor() { + return false; + } + + @Override + @Unused(implemented = true) + public boolean isMethod() { + return false; + } + + @Override + @Used(implemented = true) + public boolean isAnnotationTypeElement() { + return false; + } + + @Override + @Used(implemented = true) + public boolean isInterface() { + return false; + } + + @Override + @Used(implemented = true) + public boolean isException() { + return false; + } + + @Override + @Used(implemented = true) + public boolean isError() { + return false; + } + + @Override + @Used(implemented = true) + public boolean isEnum() { + return false; + } + + @Override + @Unused(implemented = true) + public boolean isAnnotationType() { + return false; + } + + @Override + @Used(implemented = true) + public boolean isOrdinaryClass() { + return false; + } + + @Override + @Unused(implemented = true) + public boolean isClass() { + return false; + } + + @Override + public abstract boolean isIncluded(); + + @Override + @Used(implemented = true) + public SourcePosition position() { + return SourcePositionImpl.STUB; + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/DocletElementUtils.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/DocletElementUtils.java new file mode 100644 index 0000000..927c572 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/DocletElementUtils.java @@ -0,0 +1,174 @@ +/* + * Copyright (C) 2022 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.doclava.javadoc; + +import java.util.ArrayDeque; +import java.util.Deque; +import java.util.HashMap; +import java.util.Iterator; +import java.util.NoSuchElementException; +import javax.lang.model.element.Element; +import javax.lang.model.element.ElementKind; +import javax.lang.model.element.TypeElement; +import javax.lang.model.type.TypeMirror; +import javax.lang.model.util.Elements; +import javax.lang.model.util.Types; +import jdk.javadoc.doclet.DocletEnvironment; + +class DocletElementUtils { + + private final DocletEnvironment env; + private final Types typeUtils; + private final Elements elementUtils; + + private final TypeMirror exceptionType; + private final TypeMirror errorType; + private final TypeMirror throwableType; + + private DocletElementUtils() { + throw new UnsupportedOperationException("Hide default constructor."); + } + + public DocletElementUtils(DocletEnvironment e) { + this.env = e; + this.typeUtils = e.getTypeUtils(); + this.elementUtils = e.getElementUtils(); + + this.exceptionType = getTypeByName("java.lang.Exception"); + this.errorType = getTypeByName("java.lang.Error"); + this.throwableType = getTypeByName("java.lang.Throwable"); + } + + public boolean isException(Element e) { + if (!isClass(e)) { + return false; + } + return typeUtils.isSubtype(e.asType(), exceptionType); + } + + public boolean isError(Element e) { + if (!isClass(e)) { + return false; + } + return typeUtils.isSubtype(e.asType(), errorType); + } + + public boolean isThrowable(Element e) { + if (!isClass(e)) { + return false; + } + return typeUtils.isSubtype(e.asType(), throwableType); + } + + public boolean isAnnotation(Element e) { + return e.getKind() == ElementKind.ANNOTATION_TYPE; + } + + public boolean isEnum(Element e) { + return e.getKind() == ElementKind.ENUM; + } + + public boolean isInterface(Element e) { + return e.getKind() == ElementKind.INTERFACE; + } + + public boolean isClass(Element e) { + return e.getKind() == ElementKind.CLASS; + } + + public boolean isPackage(Element e) { + return e.getKind() == ElementKind.PACKAGE; + } + + private final HashMap<String, TypeMirror> typeMirrorsCache = new HashMap<>(); + + public TypeMirror getTypeByName(String name) { + TypeMirror mirror = typeMirrorsCache.get(name); + if (mirror != null) { + return mirror; + } + TypeElement e = elementUtils.getTypeElement(name); + if (e == null || (mirror = e.asType()) == null) { + return null; + } + typeMirrorsCache.put(name, mirror); + return mirror; + } + + /** + * Return the class name without package qualifier but with enclosing class qualifier, e.g. for + * {@code java.lang.String} return {@code String} (public class); and for {@code + * java.util.Map.Entry} return {@code Map.Entry} (nested class). + * + * @param e class + * @return class name without package qualifier but with enclosing class qualifier + */ + public String getClassNameUntilNotNested(TypeElement e) { + Deque<String> acc = new ArrayDeque<>(); + var it = new EnclosingUntilNotNestedIterator(e, this); + it.forEachRemaining(nestedElement -> acc.addFirst(nestedElement.getSimpleName().toString())); + return String.join(".", acc); + } + + public TypeElement getEnclosingTypeElement(Element e) { + if (isPackage(e)) { + return null; + + } + Element encl = e.getEnclosingElement(); + if (isPackage(encl)) { + return null; + } + while (!(isClass(encl) || isEnum(encl) || isInterface(encl) || isAnnotation(encl))) { + encl = encl.getEnclosingElement(); + if (encl == null) { + return null; + } + } + return (TypeElement) encl; + } + + /** + * Iterates over the immediately lexically enclosing elements for a nested type up until type + * is no longer nested. + */ + private static class EnclosingUntilNotNestedIterator implements Iterator<TypeElement> { + + private TypeElement current; + private final DocletElementUtils utils; + + public EnclosingUntilNotNestedIterator(TypeElement typeElement, DocletElementUtils utils) { + this.current = typeElement; + this.utils = utils; + } + + @Override + public boolean hasNext() { + return (current != null); + } + + @Override + public TypeElement next() { + if (!hasNext()) { + throw new NoSuchElementException(); + } + TypeElement ret = current; + current = utils.getEnclosingTypeElement(current); + return ret; + } + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/ErrorTypeImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ErrorTypeImpl.java new file mode 100644 index 0000000..4ab82a6 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ErrorTypeImpl.java @@ -0,0 +1,61 @@ +/* + * Copyright (c) 2003, 2023, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotationDesc; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.ProgramElementDoc; +import com.sun.javadoc.Type; +import com.sun.javadoc.TypeVariable; +import java.util.Objects; +import javax.lang.model.element.TypeElement; +import javax.lang.model.type.TypeMirror; + +class ErrorTypeImpl extends ClassDocImpl { + + private final javax.lang.model.type.ErrorType errorType; + + protected ErrorTypeImpl(TypeElement el, javax.lang.model.type.ErrorType errorType, + Context context) { + super(el, context); + this.errorType = errorType; + } + + static ErrorTypeImpl create(javax.lang.model.type.ErrorType errorType, + Context context) { + var typeEl = (TypeElement) errorType.asElement(); + return (ErrorTypeImpl) context.caches.classes.computeIfAbsent(typeEl, + el -> new ErrorTypeImpl(el, errorType, context)); + } + + @Override + @Used(implemented = true) + public boolean isIncluded() { + return false; + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/ExecutableMemberDocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ExecutableMemberDocImpl.java new file mode 100644 index 0000000..933889d --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ExecutableMemberDocImpl.java @@ -0,0 +1,207 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.ExecutableMemberDoc; +import com.sun.javadoc.ParamTag; +import com.sun.javadoc.Parameter; +import com.sun.javadoc.SourcePosition; +import com.sun.javadoc.ThrowsTag; +import com.sun.javadoc.Type; +import com.sun.javadoc.TypeVariable; +import java.lang.reflect.Modifier; +import java.util.Objects; +import java.util.stream.Collectors; +import javax.lang.model.element.Element; +import javax.lang.model.element.ExecutableElement; +import javax.lang.model.element.TypeElement; +import javax.lang.model.type.TypeMirror; +import javax.lang.model.util.Elements.Origin; + +abstract class ExecutableMemberDocImpl extends MemberDocImpl<ExecutableElement> implements + ExecutableMemberDoc { + + protected final ExecutableElement executableElement; + + // Cached fields + private ClassDoc[] thrownExceptions; + private Parameter[] parameters; + private String signature; + private String flatSignature; + private TypeVariable[] typeParameters; + + protected ExecutableMemberDocImpl(ExecutableElement e, Context context) { + super(e, context); + this.executableElement = e; + } + + @Override + @Used(implemented = true) + public boolean isNative() { + return (reflectModifiers & Modifier.NATIVE) != 0; + } + + @Override + @Used(implemented = true) + public boolean isSynchronized() { + return (reflectModifiers & Modifier.SYNCHRONIZED) != 0; + } + + @Override + @Used(implemented = true) + public boolean isVarArgs() { + return executableElement.isVarArgs(); + } + + @Used(implemented = true) + public boolean isSynthetic() { + return context.environment.getElementUtils() + .getOrigin(executableElement) == Origin.SYNTHETIC; + } + + @Override + @Used(implemented = true) + public boolean isIncluded() { + return context.environment.isIncluded(executableElement); + } + + @Override + @Unused + public ThrowsTag[] throwsTags() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public ParamTag[] paramTags() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public ParamTag[] typeParamTags() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public ClassDoc[] thrownExceptions() { + if (thrownExceptions == null) { + thrownExceptions = executableElement.getThrownTypes() + .stream() + .map(typeMirror -> { + Element element = context.environment.getTypeUtils().asElement(typeMirror); + return switch (element.getKind()) { + case CLASS, INTERFACE, ENUM -> ClassDocImpl.create( + (TypeElement) element, + context); + case ANNOTATION_TYPE -> AnnotationTypeDocImpl.create( + (TypeElement) element, + context); + default -> null; + }; + }) + .filter(Objects::nonNull) + .toArray(ClassDoc[]::new); + } + return thrownExceptions; + } + + @Override + @Unused + public Type[] thrownExceptionTypes() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public Parameter[] parameters() { + if (parameters == null) { + parameters = executableElement.getParameters() + .stream() + .map(variableElement -> ParameterImpl.create(variableElement, context)) + .toArray(ParameterImpl[]::new); + } + return parameters; + } + + @Override + @Unused + public Type receiverType() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public TypeVariable[] typeParameters() { + if (typeParameters == null) { + typeParameters = executableElement.getTypeParameters() + .stream() + .map(tpe -> TypeVariableImpl.create(tpe.asType(), context)) + .toArray(TypeVariable[]::new); + } + return typeParameters; + } + + @Override + @Used(implemented = true) + public String signature() { + if (signature == null) { + String params = executableElement.getParameters() + .stream() + .map(param -> param.asType().toString()) + .collect(Collectors.joining(", ")); + signature = "(" + params + ")"; + } + return signature; + } + + @Override + @Used(implemented = true) + public String flatSignature() { + if (flatSignature == null) { + String params = executableElement.getParameters() + .stream() + .map(param -> { + TypeMirror mirror = param.asType(); + Type t = TypeImpl.create(mirror, context); + return t.simpleTypeName(); + }) + .collect(Collectors.joining(", ")); + flatSignature = "(" + params + ")"; + } + return flatSignature; + } + + @Override + @Used(implemented = true) + public SourcePosition position() { + return SourcePositionImpl.STUB; + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/FieldDocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/FieldDocImpl.java new file mode 100644 index 0000000..3f61a61 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/FieldDocImpl.java @@ -0,0 +1,142 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.FieldDoc; +import com.sun.javadoc.SerialFieldTag; +import com.sun.javadoc.Type; +import javax.lang.model.element.TypeElement; +import javax.lang.model.element.VariableElement; +import javax.lang.model.util.Elements.Origin; + +class FieldDocImpl extends MemberDocImpl<VariableElement> implements FieldDoc { + + protected final VariableElement variableElement; + + protected FieldDocImpl(VariableElement e, Context context) { + super(e, context); + variableElement = e; + } + + static FieldDocImpl create(VariableElement e, Context context) { + return context.caches.fields.computeIfAbsent(e, el -> new FieldDocImpl(el, context)); + } + + @Override + @Used(implemented = true) + public boolean isSynthetic() { + return context.environment.getElementUtils().getOrigin(variableElement) == Origin.SYNTHETIC; + } + + @Override + @Used(implemented = true) + public String name() { + return variableElement.getSimpleName().toString(); + } + + @Override + @Used(implemented = true) + public String qualifiedName() { + var enclosingClass = variableElement.getEnclosingElement(); + return switch (enclosingClass.getKind()) { + case CLASS, INTERFACE, ANNOTATION_TYPE, ENUM -> + ((TypeElement) enclosingClass).getQualifiedName().toString() + "." + + variableElement.getSimpleName(); + default -> throw new UnsupportedOperationException("Expected CLASS, INTERFACE, " + + "ANNOTATION_TYPE or ENUM, but got " + enclosingClass.getKind()); + }; + } + + @Override + @Used(implemented = true) + public boolean isIncluded() { + return context.environment.isIncluded(variableElement); + } + + @Override + @Used(implemented = true) + public Type type() { + return TypeImpl.create(variableElement.asType(), context); + } + + @Override + @Used(implemented = true) + public boolean isTransient() { + return java.lang.reflect.Modifier.isTransient(reflectModifiers); + } + + @Override + @Used(implemented = true) + public boolean isVolatile() { + return java.lang.reflect.Modifier.isVolatile(reflectModifiers); + } + + @Override + @Unused + public SerialFieldTag[] serialFieldTags() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public Object constantValue() { + var cv = variableElement.getConstantValue(); + if (cv == null) { + return null; + } + // cv is either a primitive type or a String + if (cv instanceof String) { + return cv; + } else if (cv instanceof Boolean b) { + return b; + } else if (cv instanceof Byte b) { + return (int) b; + } else if (cv instanceof Character c) { + return (int) c; + } else if (cv instanceof Double d) { + return d; + } else if (cv instanceof Float f) { + return f; + } else if (cv instanceof Integer i) { + return i; + } else if (cv instanceof Long l) { + return l; + } else if (cv instanceof Short s) { + return (int) s; + } else { + throw new IllegalArgumentException("Unexpected constant value of type " + cv.getClass() + + " when expected java.lang.String or primitive type"); + } + } + + @Override + @Unused + public String constantValueExpression() { + throw new UnsupportedOperationException("not yet implemented"); + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/MemberDocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/MemberDocImpl.java new file mode 100644 index 0000000..670c649 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/MemberDocImpl.java @@ -0,0 +1,40 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.sun.javadoc.MemberDoc; +import javax.lang.model.element.Element; + +abstract class MemberDocImpl<T extends Element> extends ProgramElementDocImpl<T> implements + MemberDoc { + + protected MemberDocImpl(T e, Context context) { + super(e, context); + } + + @Override + public abstract boolean isSynthetic(); +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/MethodDocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/MethodDocImpl.java new file mode 100644 index 0000000..50d2894 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/MethodDocImpl.java @@ -0,0 +1,158 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.MethodDoc; +import com.sun.javadoc.Type; +import javax.lang.model.element.ExecutableElement; +import javax.lang.model.element.Modifier; +import javax.lang.model.element.TypeElement; +import javax.lang.model.type.TypeKind; +import javax.lang.model.type.TypeMirror; +import javax.lang.model.util.ElementFilter; +import javax.lang.model.util.Elements; +import javax.lang.model.util.Types; + +class MethodDocImpl extends ExecutableMemberDocImpl implements MethodDoc { + + protected MethodDocImpl(ExecutableElement e, Context context) { + super(e, context); + } + + static MethodDocImpl create(ExecutableElement e, Context context) { + return context.caches.methods.computeIfAbsent(e, + el -> new MethodDocImpl(el, context)); + } + + @Override + @Used(implemented = true) + public String name() { + return executableElement.getSimpleName().toString(); + } + + @Override + @Used(implemented = true) + public String qualifiedName() { + var enclosingClass = executableElement.getEnclosingElement(); + return switch (enclosingClass.getKind()) { + case CLASS, INTERFACE, ANNOTATION_TYPE, ENUM -> { + var enclosingClassName = + ((TypeElement) enclosingClass).getQualifiedName().toString(); + yield enclosingClassName + "." + name(); + } + default -> throw new UnsupportedOperationException("Expected CLASS, INTERFACE, " + + "ANNOTATION_TYPE or ENUM, but got " + enclosingClass.getKind()); + }; + } + + @Override + @Unused(implemented = true) + public boolean isMethod() { + return true; + } + + @Override + @Used(implemented = true) + public boolean isAbstract() { + return java.lang.reflect.Modifier.isAbstract(reflectModifiers); + } + + private Boolean isDefault; + + @Override + @Used(implemented = true) + public boolean isDefault() { + if (isDefault == null) { + isDefault = executableElement.getModifiers() + .stream() + .anyMatch(m -> m == Modifier.DEFAULT); + } + return isDefault; + } + + @Override + @Used(implemented = true) + public Type returnType() { + return TypeImpl.create(executableElement.getReturnType(), context); + } + + @Override + @Unused + public ClassDoc overriddenClass() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public Type overriddenType() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public MethodDoc overriddenMethod() { + if (isStatic()) { + return null; + } + + var enclosingElement = executableElement.getEnclosingElement(); + + final Types typeUtils = context.environment.getTypeUtils(); + final Elements elemUtils = context.environment.getElementUtils(); + + return switch (enclosingElement.getKind()) { + case CLASS, INTERFACE, ANNOTATION_TYPE, ENUM -> { + var owningClass = ((TypeElement) enclosingElement); + for (TypeMirror superclass = owningClass.getSuperclass(); + superclass.getKind() != TypeKind.NONE; + superclass = ((TypeElement) typeUtils.asElement(superclass)).getSuperclass() + ) { + TypeElement superclassElem = + (TypeElement) typeUtils.asElement(superclass); + var overriden = ElementFilter.methodsIn(superclassElem.getEnclosedElements()) + .stream() + .filter(exe -> elemUtils.overrides(executableElement, exe, owningClass)) + .findFirst(); + if (overriden.isPresent()) { + yield MethodDocImpl.create(overriden.get(), context); + } + } + yield null; + } + default -> throw new UnsupportedOperationException("Expected CLASS, INTERFACE, " + + "ANNOTATION_TYPE or ENUM, but got " + enclosingElement.getKind()); + }; + } + + @Override + @Unused + public boolean overrides(MethodDoc meth) { + throw new UnsupportedOperationException("not yet implemented"); + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/PackageDocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/PackageDocImpl.java new file mode 100644 index 0000000..2c60994 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/PackageDocImpl.java @@ -0,0 +1,247 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotationDesc; +import com.sun.javadoc.AnnotationTypeDoc; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.PackageDoc; +import java.util.ArrayDeque; +import java.util.Deque; +import java.util.Iterator; +import java.util.List; +import java.util.Spliterator; +import java.util.Spliterators; +import java.util.function.Predicate; +import java.util.stream.Stream; +import java.util.stream.StreamSupport; +import javax.lang.model.element.Element; +import javax.lang.model.element.ElementKind; +import javax.lang.model.element.PackageElement; +import javax.lang.model.element.TypeElement; + +class PackageDocImpl extends DocImpl<PackageElement> implements PackageDoc { + + private final PackageElement packageElement; + + + private String qualifiedName; + private ClassDoc[] allClasses; + private ClassDoc[] allClassesFiltered; + private ClassDoc[] ordinaryClasses; + private ClassDoc[] exceptions; + private ClassDoc[] errors; + private ClassDoc[] enums; + private ClassDoc[] interfaces; + private AnnotationTypeDoc[] annotationTypes; + + protected PackageDocImpl(PackageElement e, Context context) { + super(e, context); + this.packageElement = e; + } + + static PackageDocImpl create(PackageElement e, Context context) { + var ret = context.caches.packages.computeIfAbsent(e, el -> new PackageDocImpl(el, context)); + return ret; + } + + @Override + @Used(implemented = true) + public ClassDoc[] allClasses(boolean filter) { + if (!filter && allClasses != null) { + return allClasses; + } + if (filter && allClassesFiltered != null) { + return allClassesFiltered; + } + + List<ClassDocImpl> classes = + filterEnclosedElements(e -> e.getKind() == ElementKind.CLASS || + e.getKind() == ElementKind.INTERFACE || + e.getKind() == ElementKind.ENUM || + e.getKind() == ElementKind.ANNOTATION_TYPE) + .filter(e -> !filter || context.environment.isSelected(e)) + .map(e -> { + if (e.getKind() == ElementKind.ANNOTATION_TYPE) { + return AnnotationTypeDocImpl.create((TypeElement) e, context); + } + return ClassDocImpl.create((TypeElement) e, context); + }) + .toList(); + + if (filter) { + return allClassesFiltered = classes.toArray(ClassDoc[]::new); + } else { + return allClasses = classes.toArray(ClassDoc[]::new); + } + } + + @Override + @Used(implemented = true) + public ClassDoc[] allClasses() { + return allClasses(true); + } + + private Stream<Element> filterEnclosedElements(Predicate<Element> predicate) { + EnclosedElementsIterator it = new EnclosedElementsIterator(packageElement); + return StreamSupport + .stream(Spliterators.spliteratorUnknownSize(it, Spliterator.ORDERED), false) + .filter(context.environment::isIncluded) + .filter(predicate); + } + + @Override + @Used(implemented = true) + public ClassDoc[] ordinaryClasses() { + if (ordinaryClasses == null) { + ordinaryClasses = filterEnclosedElements(e -> e.getKind() == ElementKind.CLASS) + .map(e -> ClassDocImpl.create((TypeElement) e, context)) + .filter(cls -> !cls.isError() && !cls.isException()) + .toArray(ClassDocImpl[]::new); + } + return ordinaryClasses; + } + + @Override + @Used(implemented = true) + public ClassDoc[] exceptions() { + if (exceptions == null) { + exceptions = filterEnclosedElements(e -> e.getKind() == ElementKind.CLASS) + .map(element -> ClassDocImpl.create((TypeElement) element, context)) + .filter(ClassDocImpl::isException) + .toArray(ClassDocImpl[]::new); + } + return exceptions; + } + + @Override + @Used(implemented = true) + public ClassDoc[] errors() { + if (errors == null) { + errors = filterEnclosedElements(e -> e.getKind() == ElementKind.CLASS) + .map(element -> ClassDocImpl.create((TypeElement) element, context)) + .filter(ClassDocImpl::isError) + .toArray(ClassDocImpl[]::new); + } + return errors; + } + + @Override + @Used(implemented = true) + public ClassDoc[] enums() { + if (enums == null) { + enums = filterEnclosedElements(e -> e.getKind() == ElementKind.ENUM) + .map(element -> ClassDocImpl.create((TypeElement) element, context)) + .toArray(ClassDocImpl[]::new); + } + return enums; + } + + @Override + @Used(implemented = true) + public ClassDoc[] interfaces() { + if (interfaces == null) { + interfaces = filterEnclosedElements(e -> e.getKind() == ElementKind.INTERFACE) + .map(element -> ClassDocImpl.create((TypeElement) element, context)) + .toArray(ClassDocImpl[]::new); + } + return interfaces; + } + + @Override + @Used(implemented = true) + public AnnotationTypeDoc[] annotationTypes() { + if (annotationTypes == null) { + annotationTypes = filterEnclosedElements( + e -> e.getKind() == ElementKind.ANNOTATION_TYPE) + .map(element -> AnnotationTypeDocImpl.create((TypeElement) element, context)) + .toArray(AnnotationTypeDocImpl[]::new); + } + return annotationTypes; + } + + @Override + @Unused + public AnnotationDesc[] annotations() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public ClassDoc findClass(String className) { + for (ClassDoc c : allClasses()) { + if (c.name().equals(className)) { + return c; + } + } + return null; + } + + @Override + @Used(implemented = true) + public boolean isIncluded() { + return context.environment.isIncluded(packageElement); + } + + @Override + @Used(implemented = true) + public String name() { + return qualifiedName(); + } + + @Override + public String qualifiedName() { + if (qualifiedName == null) { + qualifiedName = packageElement.getQualifiedName().toString(); + } + return qualifiedName; + } + + private static final class EnclosedElementsIterator implements Iterator<Element> { + + private final Deque<Element> queue; + + public EnclosedElementsIterator(Element element) { + this.queue = new ArrayDeque<>(element.getEnclosedElements()); + } + + @Override + public boolean hasNext() { + return !queue.isEmpty(); + } + + @Override + public Element next() { + Element current = queue.pop(); + if (!current.getEnclosedElements().isEmpty()) { + queue.addAll(current.getEnclosedElements()); + } + return current; + } + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/ParamTagImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ParamTagImpl.java new file mode 100644 index 0000000..e329cc1 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ParamTagImpl.java @@ -0,0 +1,70 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Used; +import com.sun.javadoc.ParamTag; +import com.sun.source.doctree.ParamTree; +import java.util.HashMap; +import java.util.stream.Collectors; +import javax.lang.model.element.Element; + +class ParamTagImpl extends TagImpl implements ParamTag { + + private final ParamTree paramTree; + + protected ParamTagImpl(ParamTree paramTree, Element owner, Context context) { + super(paramTree, owner, context); + this.paramTree = paramTree; + } + + static ParamTagImpl create(ParamTree paramTree, Element owner, Context context) { + var tagsOfElement = context.caches.tags.param.computeIfAbsent(owner, + el -> new HashMap<>()); + return tagsOfElement.computeIfAbsent(paramTree, el -> new ParamTagImpl(el, owner, context)); + } + + @Override + @Used(implemented = true) + public String parameterName() { + return paramTree.getName().getName().toString(); + } + + @Override + @Used(implemented = true) + public String parameterComment() { + return paramTree.getDescription() + .stream() + .map(Object::toString) + .collect(Collectors.joining(" ")); + } + + @Override + @Used(implemented = true) + public boolean isTypeParameter() { + return paramTree.isTypeParameter(); + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/ParameterImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ParameterImpl.java new file mode 100644 index 0000000..4b32607 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ParameterImpl.java @@ -0,0 +1,83 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotationDesc; +import com.sun.javadoc.Parameter; +import com.sun.javadoc.Type; +import com.sun.javadoc.TypeVariable; +import javax.lang.model.element.VariableElement; + +class ParameterImpl implements Parameter { + + private final String name; + private final Type type; + private final AnnotationDescImpl[] annotations; + + public ParameterImpl(VariableElement variableElement, Context context) { + this.name = variableElement.getSimpleName().toString(); + this.type = TypeImpl.create(variableElement.asType(), context); + this.annotations = variableElement.getAnnotationMirrors() + .stream() + .map(am -> new AnnotationDescImpl(am, context)) + .toArray(AnnotationDescImpl[]::new); + } + + static ParameterImpl create(VariableElement ve, Context context) { + return context.caches.parameters.computeIfAbsent(ve, el -> new ParameterImpl(el, context)); + } + + @Override + @Used(implemented = true) + public Type type() { + return type; + } + + @Override + @Used(implemented = true) + public String name() { + return name; + } + + @Override + @Used(implemented = true) + public String typeName() { + String result; + if (type instanceof ClassDocImpl || type instanceof TypeVariable) { + result = type.typeName() + type.dimension(); + } else { + result = type.qualifiedTypeName() + type.dimension(); + } + return result; + } + + @Override + @Used(implemented = true) + public AnnotationDesc[] annotations() { + return annotations; + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/ParameterizedTypeImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ParameterizedTypeImpl.java new file mode 100644 index 0000000..5374947 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ParameterizedTypeImpl.java @@ -0,0 +1,97 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.ParameterizedType; +import com.sun.javadoc.Type; +import java.util.Objects; +import javax.lang.model.type.DeclaredType; +import javax.lang.model.type.TypeMirror; + +class ParameterizedTypeImpl extends TypeImpl implements ParameterizedType { + + private final DeclaredType declaredType; + + // Cached fields + private Type[] typeArguments; + + protected ParameterizedTypeImpl(DeclaredType declaredType, Context context) { + super(declaredType, context); + this.declaredType = declaredType; + } + + static ParameterizedTypeImpl create(DeclaredType declaredType, Context context) { + return context.caches.types.parameterized.computeIfAbsent(declaredType, + el -> new ParameterizedTypeImpl(el, context)); + } + + @Override + @Used(implemented = true) + public ParameterizedType asParameterizedType() { + return this; + } + + @Override + @Used(implemented = true) + public Type[] typeArguments() { + if (typeArguments == null) { + typeArguments = declaredType.getTypeArguments() + .stream() + .map(typeMirror -> TypeImpl.create(typeMirror, context)) + .toArray(Type[]::new); + } + return typeArguments; + } + + @Override + @Unused + public Type superclassType() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public Type[] interfaceTypes() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public Type containingType() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + public ClassDoc asClassDoc() { + TypeMirror erasure = context.environment.getTypeUtils().erasure(declaredType); + Type type = create(erasure, context); + Objects.requireNonNull(type); + return type.asClassDoc(); + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/PrimitiveTypeImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/PrimitiveTypeImpl.java new file mode 100644 index 0000000..9bab2f7 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/PrimitiveTypeImpl.java @@ -0,0 +1,127 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotatedType; +import com.sun.javadoc.AnnotationTypeDoc; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.ParameterizedType; +import com.sun.javadoc.Type; +import com.sun.javadoc.TypeVariable; +import com.sun.javadoc.WildcardType; + +public enum PrimitiveTypeImpl implements Type { + + BOOLEAN("boolean"), + BYTE("byte"), + CHAR("char"), + DOUBLE("double"), + FLOAT("float"), + INT("int"), + LONG("long"), + SHORT("short"), + VOID("void"); + + private final String name; + + PrimitiveTypeImpl(String name) { + this.name = name; + } + + @Override + @Unused(implemented = true) + public String typeName() { + return name; + } + + @Override + @Used(implemented = true) + public String qualifiedTypeName() { + return name; + } + + @Override + @Used(implemented = true) + public String simpleTypeName() { + return name; + } + + @Override + @Used(implemented = true) + public String dimension() { + return ""; + } + + @Override + @Used(implemented = true) + public boolean isPrimitive() { + return true; + } + + @Override + @Used(implemented = true) + public ClassDoc asClassDoc() { + return null; + } + + @Override + @Used(implemented = true) + public ParameterizedType asParameterizedType() { + return null; + } + + @Override + @Used(implemented = true) + public TypeVariable asTypeVariable() { + return null; + } + + @Override + @Used(implemented = true) + public WildcardType asWildcardType() { + return null; + } + + @Override + @Used(implemented = true) + public AnnotatedType asAnnotatedType() { + return null; + } + + @Override + @Unused(implemented = true) + public AnnotationTypeDoc asAnnotationTypeDoc() { + return null; + } + + @Override + @Unused(implemented = true) + public Type getElementType() { + return null; + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/ProgramElementDocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ProgramElementDocImpl.java new file mode 100644 index 0000000..bdf49de --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ProgramElementDocImpl.java @@ -0,0 +1,183 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotationDesc; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.PackageDoc; +import com.sun.javadoc.ProgramElementDoc; +import java.util.Set; +import javax.lang.model.element.Element; +import javax.lang.model.element.ElementKind; +import javax.lang.model.element.Modifier; +import javax.lang.model.element.PackageElement; +import javax.lang.model.element.TypeElement; + +abstract class ProgramElementDocImpl<T extends Element> extends DocImpl<T> implements + ProgramElementDoc { + + /** + * Direct mapping of {@link javax.lang.model.element.Modifier} to {@link + * java.lang.reflect.Modifier}. + * + * @implNote Can be updated by subclasses ({@link ClassDocImpl} and {@link + * AnnotationTypeDocImpl} to add {@link java.lang.reflect.Modifier#INTERFACE} modifier. + * @see javax.lang.model.element.Modifier + * @see java.lang.reflect.Modifier + * @see ClassDocImpl + * @see AnnotationTypeDocImpl + */ + protected int reflectModifiers; + + protected T element; + + private AnnotationDescImpl[] annotations; + + protected ProgramElementDocImpl(T e, Context context) { + super(e, context); + + this.element = e; + this.reflectModifiers = elementModifiersToReflectModifiers(e.getModifiers()); + } + + private int elementModifiersToReflectModifiers(Set<Modifier> modifiers) { + int mods = 0; + for (Modifier m : modifiers) { + switch (m) { + case ABSTRACT -> mods |= java.lang.reflect.Modifier.ABSTRACT; + case FINAL -> mods |= java.lang.reflect.Modifier.FINAL; + case PRIVATE -> mods |= java.lang.reflect.Modifier.PRIVATE; + case PROTECTED -> mods |= java.lang.reflect.Modifier.PROTECTED; + case PUBLIC -> mods |= java.lang.reflect.Modifier.PUBLIC; + case NATIVE -> mods |= java.lang.reflect.Modifier.NATIVE; + case STATIC -> mods |= java.lang.reflect.Modifier.STATIC; + case STRICTFP -> mods |= java.lang.reflect.Modifier.STRICT; + case SYNCHRONIZED -> mods |= java.lang.reflect.Modifier.SYNCHRONIZED; + case TRANSIENT -> mods |= java.lang.reflect.Modifier.TRANSIENT; + case VOLATILE -> mods |= java.lang.reflect.Modifier.VOLATILE; + case DEFAULT, NON_SEALED, SEALED -> { + // Exhaust the remaining element modifiers that are not present in + // java.lang.reflect.Modifier. + } + default -> throw new UnsupportedOperationException("Unexpected modifier: " + m); + } + } + return mods; + } + + @Override + @Used(implemented = true) + public ClassDoc containingClass() { + Element cur = element.getEnclosingElement(); + while (cur != null && cur.getKind() != ElementKind.ANNOTATION_TYPE + && cur.getKind() != ElementKind.CLASS + && cur.getKind() != ElementKind.ENUM && cur.getKind() != ElementKind.INTERFACE) { + cur = cur.getEnclosingElement(); + } + if (cur == null) { + return null; + } + return switch (cur.getKind()) { + case CLASS, INTERFACE, ENUM, ANNOTATION_TYPE -> ClassDocImpl.create((TypeElement) cur, + context); + default -> null; + }; + } + + @Override + @Used(implemented = true) + public PackageDoc containingPackage() { + Element cur = element.getEnclosingElement(); + while (cur.getKind() != ElementKind.PACKAGE) { + cur = cur.getEnclosingElement(); + } + return PackageDocImpl.create((PackageElement) cur, context); + } + + @Override + @Unused(implemented = true) + public int modifierSpecifier() { + return reflectModifiers; + } + + @Override + @Unused(implemented = true) + public String modifiers() { + return java.lang.reflect.Modifier.toString(reflectModifiers); + } + + @Override + @Used(implemented = true) + public AnnotationDesc[] annotations() { + if (annotations == null) { + annotations = element.getAnnotationMirrors() + .stream() + // b/270334687: Filter out elements that are not ANNOTATION_TYPE + .filter(am -> ((TypeElement) am.getAnnotationType().asElement()).getKind() == ElementKind.ANNOTATION_TYPE) + .map(am -> new AnnotationDescImpl(am, context)) + .toArray(AnnotationDescImpl[]::new); + } + return annotations; + } + + @Override + @Used(implemented = true) + public boolean isPublic() { + return java.lang.reflect.Modifier.isPublic(reflectModifiers); + } + + @Override + @Used(implemented = true) + public boolean isProtected() { + return java.lang.reflect.Modifier.isProtected(reflectModifiers); + } + + @Override + @Used(implemented = true) + public boolean isPrivate() { + return java.lang.reflect.Modifier.isPrivate(reflectModifiers); + } + + @Override + @Used(implemented = true) + public boolean isPackagePrivate() { + return !(isPublic() || isPrivate() || isProtected()); + } + + @Override + @Used(implemented = true) + public boolean isStatic() { + return java.lang.reflect.Modifier.isStatic(reflectModifiers); + } + + @Override + @Used(implemented = true) + public boolean isFinal() { + return java.lang.reflect.Modifier.isFinal(reflectModifiers); + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/RootDocImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/RootDocImpl.java new file mode 100644 index 0000000..d6e412e --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/RootDocImpl.java @@ -0,0 +1,190 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.PackageDoc; +import com.sun.javadoc.RootDoc; +import com.sun.javadoc.SourcePosition; +import java.util.ArrayList; +import java.util.List; +import javax.lang.model.element.Element; +import javax.lang.model.element.ElementKind; +import javax.lang.model.element.NestingKind; +import javax.lang.model.element.PackageElement; +import javax.lang.model.element.TypeElement; +import javax.lang.model.util.ElementFilter; +import jdk.javadoc.doclet.DocletEnvironment; + +/** + * The {@code RootDocImpl} is an implementation of the "old" Doclet APIs (previously under + * {@code com.sun.javadoc.*}, deprecated since 9 and removed in 13) in terms of new Doclet APIs + * {@link jdk.javadoc.doclet.Doclet}. ({@link DocletEnvironment}). + */ +public class RootDocImpl extends DocImpl<Element> implements RootDoc { + + private ClassDoc[] classes; + + public RootDocImpl(DocletEnvironment environment) { + super(null, new Context(environment)); + + for (var e : environment.getSpecifiedElements()) { + switch (e.getKind()) { + case CLASS, INTERFACE, ENUM, ANNOTATION_TYPE -> addClass((TypeElement) e); + case PACKAGE -> PackageDocImpl.create((PackageElement) e, context); + case RECORD -> throw new UnsupportedOperationException( + "records are not yet supported."); + case MODULE -> throw new UnsupportedOperationException( + "modules are not yet supported."); + default -> throw new UnsupportedOperationException( + "Not yet supported top-level TypeElement kind:" + e.getKind()); + } + } + } + + private void addClass(TypeElement c) { + switch (c.getKind()) { + case CLASS, ENUM, INTERFACE -> ClassDocImpl.create(c, context); + case ANNOTATION_TYPE -> AnnotationTypeDocImpl.create(c, context); + default -> throw new UnsupportedOperationException( + "Unexpected element kind:" + c.getKind()); + } + // Initialize nested + // TODO: Need to ensure this is needed! + ElementFilter.typesIn(c.getEnclosedElements()) + .stream() + .filter(te -> te.getNestingKind() == NestingKind.MEMBER) + .forEach(te -> { + if (te.getKind() == ElementKind.ANNOTATION_TYPE) { + AnnotationTypeDocImpl.create(te, context); + } else { + ClassDocImpl.create(te, context); + } + }); + } + + @Override + @Unused + public String[][] options() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public PackageDoc[] specifiedPackages() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public ClassDoc[] specifiedClasses() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public ClassDoc[] classes() { + if (classes == null) { + List<ClassDoc> classesAndAnnotations = new ArrayList<>(context.caches.classes.values()); + classesAndAnnotations.addAll(context.caches.annotations.values()); + classes = classesAndAnnotations.toArray(ClassDoc[]::new); + } + return classes; + } + + @Override + @Used(implemented = true) + public ClassDoc classNamed(String qualifiedName) { + TypeElement cls = context.environment.getElementUtils().getTypeElement(qualifiedName); + return cls == null ? null : ClassDocImpl.create(cls, context); + } + + @Override + @Used(implemented = true) + public PackageDoc packageNamed(String name) { + for (PackageDoc pkg : context.caches.packages.values()) { + if (pkg.name().equals(name)) { + return pkg; + } + } + return null; + } + + @Override + @Used(implemented = true) + public String name() { + return "*! Doclava !*"; + } + + @Override + public String qualifiedName() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public boolean isIncluded() { + return false; + } + + @Override + @Unused + public void printError(String msg) { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public void printError(SourcePosition pos, String msg) { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public void printWarning(String msg) { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public void printWarning(SourcePosition pos, String msg) { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public void printNotice(String msg) { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public void printNotice(SourcePosition pos, String msg) { + throw new UnsupportedOperationException("not yet implemented"); + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/SeeTagImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/SeeTagImpl.java new file mode 100644 index 0000000..c98d04e --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/SeeTagImpl.java @@ -0,0 +1,157 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.sun.javadoc.MemberDoc; +import com.sun.javadoc.PackageDoc; +import com.sun.javadoc.SeeTag; +import com.sun.source.doctree.DocTree; +import com.sun.source.doctree.DocTree.Kind; +import com.sun.source.doctree.ReferenceTree; +import com.sun.source.doctree.SeeTree; +import java.util.HashMap; +import java.util.stream.Collectors; +import javax.lang.model.element.Element; +import javax.lang.model.element.PackageElement; +import javax.lang.model.element.TypeElement; + +class SeeTagImpl extends TagImpl implements SeeTag { + + private final SeeTree seeTree; + + protected SeeTagImpl(SeeTree seeTree, Element owner, Context context) { + super(seeTree, owner, context); + + this.seeTree = seeTree; + } + + static SeeTagImpl create(SeeTree docTree, Element owner, Context context) { + var tagsOfElement = context.caches.tags.see.computeIfAbsent(owner, + el -> new HashMap<>()); + return tagsOfElement.computeIfAbsent(docTree, + el -> new SeeTagImpl(el, owner, context)); + } + + private String label; + + @Override + @Unused(implemented = true) + public String label() { + if (label == null) { + var children = seeTree.getReference(); + label = children + .stream() + .map(DocTree::toString) + .collect(Collectors.joining(" ")); + } + return label; + } + + private boolean referencedPackageInitialised; + private PackageDocImpl referencedPackage; + + @Override + @Unused(implemented = true) + public PackageDoc referencedPackage() { + if (!referencedPackageInitialised) { + String signature = getReferenceSignature(seeTree); + if (signature != null) { + PackageElement pe = + context.environment.getElementUtils().getPackageElement(signature); + if (pe != null) { + referencedPackage = PackageDocImpl.create(pe, context); + } + } + referencedPackageInitialised = true; + } + return referencedPackage; + } + + @Override + @Unused(implemented = true) + public String referencedClassName() { + var rc = referencedClass(); + return rc.qualifiedName(); + } + + private boolean referencedClassInitialised; + private ClassDocImpl referencedClass; + + @Override + @Unused(implemented = true) + public ClassDocImpl referencedClass() { + if (!referencedClassInitialised) { + String signature = getReferenceSignature(seeTree); + if (signature != null) { + TypeElement te = context.environment.getElementUtils().getTypeElement(signature); + if (te != null) { + referencedClass = switch (te.getKind()) { + case CLASS, ENUM, INTERFACE -> ClassDocImpl.create(te, context); + case ANNOTATION_TYPE -> AnnotationTypeDocImpl.create(te, context); + default -> throw new UnsupportedOperationException(te.getKind() + + " is not yet supported"); + }; + } + } + referencedClassInitialised = true; + } + return referencedClass; + } + + @Override + @Unused(implemented = true) + public String referencedMemberName() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused(implemented = true) + public MemberDoc referencedMember() { + throw new UnsupportedOperationException("not yet implemented"); + } + + /** + * Get the signature of a reference to a Java language element (which is in a form of {@link + * ReferenceTree}) of a given {@link SeeTree}. For cases when reference is anything but {@link + * ReferenceTree} (e.g. it could be quoted-string or HTML) – return {@code null}. + * + * @param seeTree tag + * @return signature of a reference, or {@code null} if it's not referencing to a Java language + * element. + */ + private String getReferenceSignature(SeeTree seeTree) { + var children = seeTree.getReference(); + if (children.size() >= 1) { + DocTree ref = children.get(0); + if (ref.getKind() == Kind.REFERENCE) { + var asReference = (ReferenceTree) ref; + return asReference.getSignature(); + } + } + return null; + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/SerialFieldTagImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/SerialFieldTagImpl.java new file mode 100644 index 0000000..1fbfa88 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/SerialFieldTagImpl.java @@ -0,0 +1,123 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.SerialFieldTag; +import com.sun.source.doctree.SerialFieldTree; +import java.util.HashMap; +import javax.lang.model.element.Element; + +class SerialFieldTagImpl extends TagImpl implements SerialFieldTag, Comparable<Object> { + + protected SerialFieldTagImpl(SerialFieldTree serialFieldTree, Element owner, Context context) { + super(serialFieldTree, owner, context); + } + + static SerialFieldTagImpl create(SerialFieldTree serialFieldTree, Element owner, + Context context) { + var tagsOfElement = context.caches.tags.serialField + .computeIfAbsent(owner, el -> new HashMap<>()); + return tagsOfElement.computeIfAbsent(serialFieldTree, + el -> new SerialFieldTagImpl(el, owner, context)); + } + + /** + * Return the serialziable field name. + */ + @Override + @Unused + public String fieldName() { + throw new UnsupportedOperationException("not yet implemented"); + } + + /** + * Return the field type string. + */ + @Override + public String fieldType() { + throw new UnsupportedOperationException("not yet implemented"); + } + + /** + * Return the ClassDocImpl for field type. + * + * @returns null if no ClassDocImpl for field type is visible from containingClass context. + */ + @Override + @Unused + public ClassDoc fieldTypeDoc() { + throw new UnsupportedOperationException("not yet implemented"); + } + + /** + * Return the field comment. If there is no serialField comment, return javadoc comment of + * corresponding FieldDocImpl. + */ + @Override + @Unused + public String description() { + throw new UnsupportedOperationException("not yet implemented"); + } + + /** + * Return the kind of this tag. + */ + @Override + @Used(implemented = true) + public String kind() { + return "@serialField"; + } + + /** + * Convert this object to a string. + */ + @Unused + public String toString() { + throw new UnsupportedOperationException("not yet implemented"); + } + + /** + * Compares this Object with the specified Object for order. Returns a negative integer, zero, + * or a positive integer as this Object is less than, equal to, or greater than the given + * Object. + * <p> + * Included to make SerialFieldTagImpl items java.lang.Comparable. + * + * @param obj the <code>Object</code> to be compared. + * @return a negative integer, zero, or a positive integer as this Object is less than, equal + * to, or greater than the given Object. + * @throws ClassCastException the specified Object's type prevents it from being compared to + * this Object. + * @since 1.2 + */ + @Override + public int compareTo(Object obj) { + throw new UnsupportedOperationException("not yet implemented"); + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/SourcePositionImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/SourcePositionImpl.java new file mode 100644 index 0000000..7813498 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/SourcePositionImpl.java @@ -0,0 +1,59 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Used; +import com.sun.javadoc.SourcePosition; +import java.io.File; + +class SourcePositionImpl implements SourcePosition { + + public static final SourcePositionImpl STUB = new SourcePositionImpl(); + + private final File file; + + public SourcePositionImpl() { + this.file = new File("."); + } + + @Override + @Used(implemented = true) + public File file() { + return file; + } + + @Override + @Used(implemented = true) + public int line() { + return 0; + } + + @Override + @Used(implemented = true) + public int column() { + return 0; + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/TagImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/TagImpl.java new file mode 100644 index 0000000..2aea77e --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/TagImpl.java @@ -0,0 +1,158 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.Doc; +import com.sun.javadoc.SourcePosition; +import com.sun.javadoc.Tag; +import com.sun.source.doctree.BlockTagTree; +import com.sun.source.doctree.DocTree; +import com.sun.source.doctree.DocTree.Kind; +import com.sun.source.doctree.InlineTagTree; +import com.sun.source.doctree.ParamTree; +import com.sun.source.doctree.SeeTree; +import com.sun.source.doctree.SerialFieldTree; +import com.sun.source.doctree.ThrowsTree; +import com.sun.source.util.SimpleDocTreeVisitor; +import java.util.HashMap; +import java.util.Objects; +import javax.lang.model.element.Element; + +class TagImpl implements Tag { + + protected final DocTree docTree; + protected final Element owner; + protected final Context context; + + protected TagImpl(DocTree docTree, Element owner, Context context) { + this.docTree = docTree; + this.owner = owner; + this.context = context; + } + + static TagImpl create(DocTree docTree, Element owner, Context context) { + return switch (docTree.getKind()) { + case SEE -> SeeTagImpl.create((SeeTree) docTree, owner, context); + case PARAM -> ParamTagImpl.create((ParamTree) docTree, owner, context); + case SERIAL_FIELD -> SerialFieldTagImpl.create((SerialFieldTree) docTree, + owner, context); + case THROWS -> ThrowsTagImpl.create((ThrowsTree) docTree, owner, context); + default -> { + var tagsOfElement = context.caches.tags.generic.computeIfAbsent(owner, + el -> new HashMap<>()); + yield tagsOfElement.computeIfAbsent(docTree, el -> new TagImpl(el, owner, + context)); + } + }; + } + + private String name; + + @Override + @Used(implemented = true) + public String name() { + if (name == null) { + name = "@" + NAME_VISITOR.visit(docTree, context); + } + return name; + } + + @Override + @Unused(implemented = true) + public Doc holder() { + return context.obtain(owner); + } + + private String kind; + + @Override + @Used(implemented = true) + public String kind() { + if (kind == null) { + kind = "@" + remapKind(NAME_VISITOR.visit(docTree, context)); + } + return kind; + } + + static String remapKind(String name) { + Objects.requireNonNull(name); + return switch (name) { + case "exception" -> "throws"; + case "link", "linkplain" -> "see"; + case "serialData" -> "serial"; + default -> name; + }; + } + + private String text; + + @Override + @Used(implemented = true) + public String text() { + if (text == null) { + text = docTree.toString(); + } + return text; + } + + @Override + @Unused + public Tag[] inlineTags() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Unused + public Tag[] firstSentenceTags() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public SourcePosition position() { + return SourcePositionImpl.STUB; + } + + private static final SimpleDocTreeVisitor<String, Context> NAME_VISITOR = + new SimpleDocTreeVisitor<>() { + @Override + protected String defaultAction(DocTree node, Context context) { + if (node instanceof BlockTagTree bt) { + return bt.getTagName(); + } + if (node instanceof InlineTagTree it) { + return it.getTagName(); + } + if (node.getKind() == Kind.ERRONEOUS) { + System.err.println("Malformed tag: " + node.toString()); + return "erroneous"; + } + return node.getKind().toString().toLowerCase(); + } + }; +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/ThrowsTagImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ThrowsTagImpl.java new file mode 100644 index 0000000..fb40697 --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/ThrowsTagImpl.java @@ -0,0 +1,121 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.ThrowsTag; +import com.sun.javadoc.Type; +import com.sun.source.doctree.DocTree; +import com.sun.source.doctree.ThrowsTree; +import java.util.HashMap; +import java.util.stream.Collectors; +import javax.lang.model.element.Element; +import javax.lang.model.element.TypeElement; + +class ThrowsTagImpl extends TagImpl implements ThrowsTag { + + private final ThrowsTree throwsTree; + + protected ThrowsTagImpl(ThrowsTree throwsTree, Element owner, Context context) { + super(throwsTree, owner, context); + + this.throwsTree = throwsTree; + } + + static ThrowsTagImpl create(ThrowsTree throwsTree, Element owner, Context context) { + var tagsOfElement = context.caches.tags.throwz.computeIfAbsent(owner, + el -> new HashMap<>()); + return tagsOfElement.computeIfAbsent(throwsTree, + el -> new ThrowsTagImpl(el, owner, context)); + } + + private boolean exceptionNameInitialised; + private String exceptionName; + + @Override + @Used(implemented = true) + public String exceptionName() { + if (!exceptionNameInitialised) { + var ref = throwsTree.getExceptionName(); + if (ref != null) { + String signature = ref.getSignature(); + var lastDotPos = signature.lastIndexOf("."); + exceptionName = signature.substring(lastDotPos + 1); + } + exceptionNameInitialised = true; + } + return exceptionName; + } + + private boolean exceptionCommentInitialised; + private String exceptionComment; + + @Override + @Used(implemented = true) + public String exceptionComment() { + if (!exceptionCommentInitialised) { + var desc = throwsTree.getDescription(); + if (desc != null) { + exceptionComment = desc.stream() + .map(DocTree::toString) + .collect(Collectors.joining(" ")); + } + exceptionCommentInitialised = true; + } + return exceptionComment; + } + + private boolean exceptionInitialised; + private ClassDocImpl exception; + + @Override + @Used(implemented = true) + public ClassDoc exception() { + if (!exceptionInitialised) { + var ref = throwsTree.getExceptionName(); + if (ref != null) { + String signature = ref.getSignature(); + if (signature != null) { + TypeElement te = + context.environment.getElementUtils().getTypeElement(signature); + if (te != null) { + exception = ClassDocImpl.create(te, context); + } + } + } + exceptionInitialised = true; + } + return exception; + } + + @Override + @Unused + public Type exceptionType() { + throw new UnsupportedOperationException("not yet implemented"); + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/TypeImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/TypeImpl.java new file mode 100644 index 0000000..96b2c2e --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/TypeImpl.java @@ -0,0 +1,240 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotatedType; +import com.sun.javadoc.AnnotationTypeDoc; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.ParameterizedType; +import com.sun.javadoc.Type; +import com.sun.javadoc.TypeVariable; +import com.sun.javadoc.WildcardType; +import javax.lang.model.element.ElementKind; +import javax.lang.model.element.TypeElement; +import javax.lang.model.type.ArrayType; +import javax.lang.model.type.DeclaredType; +import javax.lang.model.type.ErrorType; +import javax.lang.model.type.PrimitiveType; +import javax.lang.model.type.TypeMirror; +import javax.lang.model.util.SimpleTypeVisitor14; + +abstract class TypeImpl implements Type { + + protected final TypeMirror typeMirror; + protected final Context context; + + protected TypeImpl(TypeMirror typeMirror, Context context) { + this.typeMirror = typeMirror; + this.context = context; + } + + protected static Type create(TypeMirror m, Context context) { + return switch (m.getKind()) { + // primitive types + case BOOLEAN -> PrimitiveTypeImpl.BOOLEAN; + case BYTE -> PrimitiveTypeImpl.BYTE; + case CHAR -> PrimitiveTypeImpl.CHAR; + case DOUBLE -> PrimitiveTypeImpl.DOUBLE; + case FLOAT -> PrimitiveTypeImpl.FLOAT; + case INT -> PrimitiveTypeImpl.INT; + case LONG -> PrimitiveTypeImpl.LONG; + case SHORT -> PrimitiveTypeImpl.SHORT; + // void is also a "primitive type" + case VOID -> PrimitiveTypeImpl.VOID; + // arrays + case ARRAY -> { + yield ArrayTypeImpl.create((ArrayType) m, context); + } + // complex types + case WILDCARD -> { + var wildcardType = (javax.lang.model.type.WildcardType) m; + yield WildcardTypeImpl.create(wildcardType, context); + } + case TYPEVAR -> { + var typeVar = (javax.lang.model.type.TypeVariable) m; + yield TypeVariableImpl.create(typeVar, context); + } + case DECLARED -> { + var dt = (DeclaredType) m; + // Order matters! AnnotatedTypeImpl goes first as it has an "underlying type" + // which will be constructed by this method in create() routine. + if (!dt.getAnnotationMirrors().isEmpty()) { + yield AnnotatedTypeImpl.create(dt, context); + } + if (!dt.getTypeArguments().isEmpty()) { + yield ParameterizedTypeImpl.create(dt, context); + } + //TODO: check that it will cast. + var el = (TypeElement) dt.asElement(); + if (el.getKind() == ElementKind.ANNOTATION_TYPE) { + yield AnnotationTypeDocImpl.create(el, context); + } + yield ClassDocImpl.create(el, context); + } + case NONE -> { + // e.g. Object.superclass() + yield null; + } + case ERROR -> { + var errorType = (ErrorType) m; + var el = (TypeElement) errorType.asElement(); + if (el.getKind() == ElementKind.ANNOTATION_TYPE) { + yield AnnotationTypeDocImpl.create(el, context); + } + yield ErrorTypeImpl.create(errorType, context); + } + default -> throw new IllegalArgumentException( + "Unexpected type of kind: " + m.getKind()); + }; + } + + @Override + @Unused + public String typeName() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = false) // Not all cases covered yet in QUALIFIED_NAME_VISITOR + public String qualifiedTypeName() { + return QUALIFIED_NAME_VISITOR.visit(typeMirror, context); + } + + @Override + @Unused(implemented = true) + public Type getElementType() { + return null; + } + + @Override + @Used(implemented = true) + public String simpleTypeName() { + var qualifiedTypeName = QUALIFIED_NAME_VISITOR.visit(typeMirror, context); + return qualifiedTypeName.substring(qualifiedTypeName.lastIndexOf('.') + 1); + } + + @Override + @Used(implemented = true) + public String dimension() { + return ""; + } + + @Override + @Used(implemented = true) + public boolean isPrimitive() { + return false; + } + + @Override + @Used(implemented = true) + public ClassDoc asClassDoc() { + return null; + } + + @Override + @Used(implemented = true) + public TypeVariable asTypeVariable() { + return null; + } + + @Override + @Used(implemented = true) + public WildcardType asWildcardType() { + return null; + } + + @Override + @Used(implemented = true) + public ParameterizedType asParameterizedType() { + return null; + } + + @Override + @Unused(implemented = true) + public AnnotationTypeDoc asAnnotationTypeDoc() { + return null; + } + + @Override + @Used(implemented = true) + public AnnotatedType asAnnotatedType() { + return null; + } + + private static final SimpleTypeVisitor14<String, Context> QUALIFIED_NAME_VISITOR = new SimpleTypeVisitor14<>() { + @Override + public String visitPrimitive(PrimitiveType t, Context context) { + return switch (t.getKind()) { + case BOOLEAN -> "boolean"; + case BYTE -> "byte"; + case CHAR -> "char"; + case DOUBLE -> "double"; + case FLOAT -> "float"; + case INT -> "int"; + case LONG -> "long"; + case SHORT -> "short"; + default -> throw new IllegalArgumentException("Unexpected primitive type with " + + "kind: " + t.getKind()); + }; + } + + @Override + public String visitTypeVariable(javax.lang.model.type.TypeVariable t, Context context) { + return t.asElement().toString(); + } + + @Override + public String visitDeclared(DeclaredType t, Context context) { + final String typeName = t.asElement().toString(); + + if (typeName.contains("<")) { + throw new RuntimeException(); + } + + return typeName; + } + + @Override + public String visitArray(ArrayType t, Context context) { + return this.visit(t.getComponentType(), context); + } + + @Override + public String visitWildcard(javax.lang.model.type.WildcardType t, Context context) { + //TODO: hack + return "?"; + //return super.visitWildcard(t, context); + } + + @Override + protected String defaultAction(TypeMirror e, Context context) { + throw new UnsupportedOperationException( + "Name visitor is not yet implemented for " + e.getKind()); + } + }; +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/TypeVariableImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/TypeVariableImpl.java new file mode 100644 index 0000000..ccc8aab --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/TypeVariableImpl.java @@ -0,0 +1,93 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import com.sun.javadoc.AnnotationDesc; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.ProgramElementDoc; +import com.sun.javadoc.Type; +import com.sun.javadoc.TypeVariable; +import java.util.Objects; +import javax.lang.model.type.TypeMirror; + +class TypeVariableImpl extends TypeImpl implements TypeVariable { + + private final javax.lang.model.type.TypeVariable typeVariable; + + protected TypeVariableImpl(javax.lang.model.type.TypeVariable typeVariable, Context context) { + super(typeVariable, context); + this.typeVariable = typeVariable; + } + + static TypeVariableImpl create(javax.lang.model.type.TypeVariable typeVariable, + Context context) { + return context.caches.types.typevar.computeIfAbsent(typeVariable, + el -> new TypeVariableImpl(typeVariable, context)); + } + + @Override + @Used(implemented = true) + public Type[] bounds() { + return new Type[0]; + } + + @Override + @Used(implemented = true) + public ClassDoc asClassDoc() { + TypeMirror erasure = context.environment.getTypeUtils().erasure(typeVariable); + Type type = create(erasure, context); + Objects.requireNonNull(type); + return type.asClassDoc(); + } + + @Override + @Unused + public ProgramElementDoc owner() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public TypeVariable asTypeVariable() { + return this; + } + + @Override + @Unused + public AnnotationDesc[] annotations() { + throw new UnsupportedOperationException("not yet implemented"); + } + + @Override + @Used(implemented = true) + public String typeName() { + TypeMirror erasure = context.environment.getTypeUtils().erasure(typeVariable); + Type type = create(erasure, context); + return type.typeName(); + } +} diff --git a/doclet_adapter/src/main/java/com/google/doclava/javadoc/WildcardTypeImpl.java b/doclet_adapter/src/main/java/com/google/doclava/javadoc/WildcardTypeImpl.java new file mode 100644 index 0000000..077a70e --- /dev/null +++ b/doclet_adapter/src/main/java/com/google/doclava/javadoc/WildcardTypeImpl.java @@ -0,0 +1,85 @@ +/* + * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.google.doclava.javadoc; + +import com.google.doclava.annotation.Used; +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.Type; +import java.util.Objects; +import javax.lang.model.type.TypeMirror; +import javax.lang.model.type.WildcardType; + +class WildcardTypeImpl extends TypeImpl implements com.sun.javadoc.WildcardType { + + private final WildcardType wildcardType; + + protected WildcardTypeImpl(WildcardType wildcardType, Context context) { + super(wildcardType, context); + this.wildcardType = wildcardType; + } + + static WildcardTypeImpl create(WildcardType wildcardType, Context context) { + return context.caches.types.wildcard.computeIfAbsent(wildcardType, + el -> new WildcardTypeImpl(wildcardType, context)); + } + + @Override + @Used(implemented = true) + public ClassDoc asClassDoc() { + TypeMirror erasure = context.environment.getTypeUtils().erasure(wildcardType); + Type type = create(erasure, context); + Objects.requireNonNull(type); + return type.asClassDoc(); + } + + @Override + @Used(implemented = true) + public com.sun.javadoc.WildcardType asWildcardType() { + return this; + } + + @Override + @Used(implemented = true) + public Type[] extendsBounds() { + TypeMirror extendsBound = wildcardType.getExtendsBound(); + if (extendsBound == null) { + return new Type[0]; + } + return new Type[]{TypeImpl.create(extendsBound, context)}; + } + + @Override + @Used(implemented = true) + public Type[] superBounds() { + TypeMirror superBounds = wildcardType.getSuperBound(); + if (superBounds == null) { + return new Type[0]; + } + return new Type[]{TypeImpl.create(superBounds, context)}; + } + + +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/AnnotatedType.java b/doclet_adapter/src/main/java/com/sun/javadoc/AnnotatedType.java new file mode 100644 index 0000000..a91eaac --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/AnnotatedType.java @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents an annotated type. + * For example: + * <pre> + * {@code @NonNull String} + * {@code @Positive int} + * </pre> + * + * @author Mahmood Ali + * @since 1.8 + */ +public interface AnnotatedType extends Type { + + @Unused + AnnotationDesc[] annotations(); + + @Used + Type underlyingType(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationDesc.java b/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationDesc.java new file mode 100644 index 0000000..db4cd8a --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationDesc.java @@ -0,0 +1,93 @@ +/* + * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents an annotation. + * An annotation associates a value with each element of an annotation type. + * + * @author Scott Seligman + * @since 1.5 + */ +public interface AnnotationDesc { + + /** + * Returns the annotation type of this annotation. + * + * @return the annotation type of this annotation. + */ + @Used + AnnotationTypeDoc annotationType(); + + /** + * Returns this annotation's elements and their values. + * Only those explicitly present in the annotation are + * included, not those assuming their default values. + * Returns an empty array if there are none. + * + * @return this annotation's elements and their values. + */ + @Used + ElementValuePair[] elementValues(); + + /** + * Check for the synthesized bit on the annotation. + * + * @return true if the annotation is synthesized. + */ + @Unused + boolean isSynthesized(); + + /** + * Represents an association between an annotation type element + * and one of its values. + * + * @author Scott Seligman + * @since 1.5 + */ + interface ElementValuePair { + + /** + * Returns the annotation type element. + * + * @return the annotation type element. + */ + @Used + AnnotationTypeElementDoc element(); + + /** + * Returns the value associated with the annotation type element. + * + * @return the value associated with the annotation type element. + */ + @Used + AnnotationValue value(); + } +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationTypeDoc.java b/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationTypeDoc.java new file mode 100644 index 0000000..e090eba --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationTypeDoc.java @@ -0,0 +1,47 @@ +/* + * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + + +import com.google.doclava.annotation.Used; + +/** + * Represents an annotation type. + * + * @author Scott Seligman + * @since 1.5 + */ +public interface AnnotationTypeDoc extends ClassDoc { + + /** + * Returns the elements of this annotation type. + * Returns an empty array if there are none. + * + * @return the elements of this annotation type. + */ + @Used + AnnotationTypeElementDoc[] elements(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationTypeElementDoc.java b/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationTypeElementDoc.java new file mode 100644 index 0000000..90536da --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationTypeElementDoc.java @@ -0,0 +1,47 @@ +/* + * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + + +import com.google.doclava.annotation.Used; + +/** + * Represents an element of an annotation type. + * + * @author Scott Seligman + * @since 1.5 + */ +public interface AnnotationTypeElementDoc extends MethodDoc { + + /** + * Returns the default value of this element. + * Returns null if this element has no default. + * + * @return the default value of this element. + */ + @Used + AnnotationValue defaultValue(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationValue.java b/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationValue.java new file mode 100644 index 0000000..2caef62 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/AnnotationValue.java @@ -0,0 +1,64 @@ +/* + * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents a value of an annotation type element. + * + * @author Scott Seligman + * @since 1.5 + */ +public interface AnnotationValue { + + /** + * Returns the value. + * The type of the returned object is one of the following: + * <ul><li> a wrapper class for a primitive type + * <li> <code>String</code> + * <li> <code>Type</code> (representing a class literal) + * <li> <code>FieldDoc</code> (representing an enum constant) + * <li> <code>AnnotationDesc</code> + * <li> <code>AnnotationValue[]</code> + * </ul> + * + * @return the value. + */ + @Used + Object value(); + + /** + * Returns a string representation of the value. + * + * @return the text of a Java language annotation value expression + * whose value is the value of this element. + */ + @Unused + String toString(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/ClassDoc.java b/doclet_adapter/src/main/java/com/sun/javadoc/ClassDoc.java new file mode 100644 index 0000000..8318feb --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/ClassDoc.java @@ -0,0 +1,368 @@ +/* + * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents a java class or interface and provides access to + * information about the class, the class's comment and tags, and the + * members of the class. A ClassDoc only exists if it was + * processed in this run of javadoc. References to classes + * which may or may not have been processed in this run are + * referred to using Type (which can be converted to ClassDoc, + * if possible). + * + * @see Type + * + * @since 1.2 + * @author Kaiyang Liu (original) + * @author Robert Field (rewrite) + */ +public interface ClassDoc extends ProgramElementDoc, Type { + + /** + * Return true if this class is abstract. Return true + * for all interfaces. + */ + @Used + boolean isAbstract(); + + /** + * Return true if this class implements or interface extends + * <code>java.io.Serializable</code>. + * + * Since <code>java.io.Externalizable</code> extends + * <code>java.io.Serializable</code>, + * Externalizable objects are also Serializable. + */ + @Unused + boolean isSerializable(); + + /** + * Return true if this class implements or interface extends + * <code>java.io.Externalizable</code>. + */ + @Unused + boolean isExternalizable(); + + /** + * Return the serialization methods for this class or + * interface. + * + * @return an array of MethodDoc objects that represents + * the serialization methods for this class or interface. + */ + @Unused + MethodDoc[] serializationMethods(); + + /** + * Return the Serializable fields of this class or interface. + * <p> + * Return either a list of default fields documented by + * <code>serial</code> tag<br> + * or return a single <code>FieldDoc</code> for + * <code>serialPersistentField</code> member. + * There should be a <code>serialField</code> tag for + * each Serializable field defined by an <code>ObjectStreamField</code> + * array component of <code>serialPersistentField</code>. + * + * @return an array of <code>FieldDoc</code> objects for the Serializable + * fields of this class or interface. + * + * @see #definesSerializableFields() + * @see SerialFieldTag + */ + @Unused + FieldDoc[] serializableFields(); + + /** + * Return true if Serializable fields are explicitly defined with + * the special class member <code>serialPersistentFields</code>. + * + * @see #serializableFields() + * @see SerialFieldTag + */ + @Unused + boolean definesSerializableFields(); + + /** + * Return the superclass of this class. Return null if this is an + * interface. + * + * <p> <i>This method cannot accommodate certain generic type constructs. + * The <code>superclassType</code> method should be used instead.</i> + * + * @return the ClassDoc for the superclass of this class, null if + * there is no superclass. + * @see #superclassType + */ + @Used + ClassDoc superclass(); + + /** + * Return the superclass of this class. Return null if this is an + * interface. A superclass is represented by either a + * <code>ClassDoc</code> or a <code>ParametrizedType</code>. + * + * @return the superclass of this class, or null if there is no superclass. + * @since 1.5 + */ + @Used + Type superclassType(); + + /** + * Test whether this class is a subclass of the specified class. + * If this is an interface, return false for all classes except + * <code>java.lang.Object</code> (we must keep this unexpected + * behavior for compatibility reasons). + * + * @param cd the candidate superclass. + * @return true if cd is a superclass of this class. + */ + @Unused + boolean subclassOf(ClassDoc cd); + + /** + * Return interfaces implemented by this class or interfaces extended + * by this interface. Includes only directly-declared interfaces, not + * inherited interfaces. + * Return an empty array if there are no interfaces. + * + * <p> <i>This method cannot accommodate certain generic type constructs. + * The <code>interfaceTypes</code> method should be used instead.</i> + * + * @return an array of ClassDoc objects representing the interfaces. + * @see #interfaceTypes + */ + @Unused + ClassDoc[] interfaces(); + + /** + * Return interfaces implemented by this class or interfaces extended + * by this interface. Includes only directly-declared interfaces, not + * inherited interfaces. + * Return an empty array if there are no interfaces. + * + * @return an array of interfaces, each represented by a + * <code>ClassDoc</code> or a <code>ParametrizedType</code>. + * @since 1.5 + */ + @Used + Type[] interfaceTypes(); + + /** + * Return the formal type parameters of this class or interface. + * Return an empty array if there are none. + * + * @return the formal type parameters of this class or interface. + * @since 1.5 + */ + @Used + TypeVariable[] typeParameters(); + + /** + * Return the type parameter tags of this class or interface. + * Return an empty array if there are none. + * + * @return the type parameter tags of this class or interface. + * @since 1.5 + */ + @Unused + ParamTag[] typeParamTags(); + + /** + * Return + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a> + * fields in this class or interface. + * Excludes enum constants if this is an enum type. + * + * @return an array of FieldDoc objects representing the included + * fields in this class or interface. + */ + @Unused + FieldDoc[] fields(); + + /** + * Return fields in this class or interface, filtered to the specified + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access + * modifier option</a>. + * Excludes enum constants if this is an enum type. + * + * @param filter Specify true to filter according to the specified access + * modifier option. + * Specify false to include all fields regardless of + * access modifier option. + * @return an array of FieldDoc objects representing the included + * fields in this class or interface. + */ + @Used + FieldDoc[] fields(boolean filter); + + /** + * Return the enum constants if this is an enum type. + * Return an empty array if there are no enum constants, or if + * this is not an enum type. + * + * @return the enum constants if this is an enum type. + */ + @Used + FieldDoc[] enumConstants(); + + /** + * Return + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a> + * methods in this class or interface. + * Same as <code>methods(true)</code>. + * + * @return an array of MethodDoc objects representing the included + * methods in this class or interface. Does not include + * constructors or annotation type elements. + */ + @Unused + MethodDoc[] methods(); + + /** + * Return methods in this class or interface, filtered to the specified + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access + * modifier option</a>. Does not include constructors or annotation + * type elements. + * + * @param filter Specify true to filter according to the specified access + * modifier option. + * Specify false to include all methods regardless of + * access modifier option. + * @return an array of MethodDoc objects representing the included + * methods in this class or interface. + */ + @Used + MethodDoc[] methods(boolean filter); + + /** + * Return + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a> + * constructors in this class. An array containing the default + * no-arg constructor is returned if no other constructors exist. + * Return empty array if this is an interface. + * + * @return an array of ConstructorDoc objects representing the included + * constructors in this class. + */ + @Unused + ConstructorDoc[] constructors(); + + /** + * Return constructors in this class, filtered to the specified + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access + * modifier option</a>. Return an array containing the default + * no-arg constructor if no other constructors exist. + * + * @param filter Specify true to filter according to the specified access + * modifier option. + * Specify false to include all constructors regardless of + * access modifier option. + * @return an array of ConstructorDoc objects representing the included + * constructors in this class. + */ + @Used + ConstructorDoc[] constructors(boolean filter); + + + /** + * Return + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a> + * nested classes and interfaces within this class or interface. + * This includes both static and non-static nested classes. + * (This method should have been named <code>nestedClasses()</code>, + * as inner classes are technically non-static.) Anonymous and local classes + * or interfaces are not included. + * + * @return an array of ClassDoc objects representing the included classes + * and interfaces defined in this class or interface. + */ + @Used + ClassDoc[] innerClasses(); + + /** + * Return nested classes and interfaces within this class or interface + * filtered to the specified + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access + * modifier option</a>. + * This includes both static and non-static nested classes. + * Anonymous and local classes are not included. + * + * @param filter Specify true to filter according to the specified access + * modifier option. + * Specify false to include all nested classes regardless of + * access modifier option. + * @return a filtered array of ClassDoc objects representing the included + * classes and interfaces defined in this class or interface. + */ + @Used + ClassDoc[] innerClasses(boolean filter); + + /** + * Find the specified class or interface within the context of this class doc. + * Search order: 1) qualified name, 2) nested in this class or interface, + * 3) in this package, 4) in the class imports, 5) in the package imports. + * Return the ClassDoc if found, null if not found. + */ + @Used + ClassDoc findClass(String className); + + /** + * Get the list of classes and interfaces declared as imported. + * These are called "single-type-import declarations" in + * <cite>The Java™ Language Specification</cite>. + * + * @return an array of ClassDoc representing the imported classes. + * + * @deprecated Import declarations are implementation details that + * should not be exposed here. In addition, not all imported + * classes are imported through single-type-import declarations. + */ + @Deprecated + @Unused + ClassDoc[] importedClasses(); + + /** + * Get the list of packages declared as imported. + * These are called "type-import-on-demand declarations" in + * <cite>The Java™ Language Specification</cite>. + * + * @return an array of PackageDoc representing the imported packages. + * + * @deprecated Import declarations are implementation details that + * should not be exposed here. In addition, this method's + * return type does not allow for all type-import-on-demand + * declarations to be returned. + */ + @Deprecated + @Unused + PackageDoc[] importedPackages(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/ConstructorDoc.java b/doclet_adapter/src/main/java/com/sun/javadoc/ConstructorDoc.java new file mode 100644 index 0000000..f7f115b --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/ConstructorDoc.java @@ -0,0 +1,35 @@ +/* + * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +/** + * Represents a constructor of a java class. + * + * @since 1.2 + * @author Robert Field + */ +public interface ConstructorDoc extends ExecutableMemberDoc { +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/Doc.java b/doclet_adapter/src/main/java/com/sun/javadoc/Doc.java new file mode 100644 index 0000000..18f7660 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/Doc.java @@ -0,0 +1,290 @@ +/* + * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import java.text.BreakIterator; +import java.util.Locale; + +/** + * Represents Java language constructs (package, class, constructor, + * method, field) which have comments and have been processed by this + * run of javadoc. All Doc objects are unique, that is, they + * are == comparable. + * + * @since 1.2 + * @author Robert Field + * @author Scott Seligman (generics, enums, annotations) + */ +public interface Doc extends Comparable<Object> { + + /** + * Return the text of the comment for this doc item. + * Tags have been removed. + */ + @Unused + String commentText(); + + /** + * Return all tags in this Doc item. + * + * @return an array of {@link Tag} objects containing all tags on + * this Doc item. + */ + @Unused + Tag[] tags(); + + /** + * Return tags of the specified {@linkplain Tag#kind() kind} in + * this Doc item. + * + * For example, if 'tagname' has value "@serial", all tags in + * this Doc item of kind "@serial" will be returned. + * + * @param tagname name of the tag kind to search for. + * @return an array of Tag containing all tags whose 'kind()' + * matches 'tagname'. + */ + @Unused + Tag[] tags(String tagname); + + /** + * Return the see also tags in this Doc item. + * + * @return an array of SeeTag containing all @see tags. + */ + @Unused + SeeTag[] seeTags(); + + /** + * Return comment as an array of tags. Includes inline tags + * (i.e. {@link <i>reference</i>} tags) but not + * block tags. + * Each section of plain text is represented as a {@link Tag} + * of {@linkplain Tag#kind() kind} "Text". + * Inline tags are represented as a {@link SeeTag} of kind "@see" + * and name "@link". + * + * @return an array of {@link Tag}s representing the comment + */ + @Used + Tag[] inlineTags(); + + /** + * Return the first sentence of the comment as an array of tags. + * Includes inline tags + * (i.e. {@link <i>reference</i>} tags) but not + * block tags. + * Each section of plain text is represented as a {@link Tag} + * of {@linkplain Tag#kind() kind} "Text". + * Inline tags are represented as a {@link SeeTag} of kind "@see" + * and name "@link". + * <p> + * If the locale is English language, the first sentence is + * determined by the rules described in the Java Language + * Specification (first version): "This sentence ends + * at the first period that is followed by a blank, tab, or + * line terminator or at the first tagline.", in + * addition a line will be terminated by block + * HTML tags: <p> </p> <h1> + * <h2> <h3> <h4> <h5> <h6> + * <hr> <pre> or </pre>. + * If the locale is not English, the sentence end will be + * determined by + * {@link BreakIterator#getSentenceInstance(Locale)}. + + * @return an array of {@link Tag}s representing the + * first sentence of the comment + */ + @Unused + Tag[] firstSentenceTags(); + + /** + * Return the full unprocessed text of the comment. Tags + * are included as text. Used mainly for store and retrieve + * operations like internalization. + */ + @Used + String getRawCommentText(); + + /** + * Set the full unprocessed text of the comment. Tags + * are included as text. Used mainly for store and retrieve + * operations like internalization. + */ + @Unused + void setRawCommentText(String rawDocumentation); + + /** + * Returns the non-qualified name of this Doc item. + * + * @return the name + */ + @Used + String name(); + + /** + * Compares this doc object with the specified object for order. Returns a + * negative integer, zero, or a positive integer as this doc object is less + * than, equal to, or greater than the given object. + * <p> + * This method satisfies the {@link java.lang.Comparable} interface. + * + * @param obj the <code>Object</code> to be compared. + * @return a negative integer, zero, or a positive integer as this Object + * is less than, equal to, or greater than the given Object. + * @exception ClassCastException the specified Object's type prevents it + * from being compared to this Object. + */ + int compareTo(Object obj); + + /** + * Is this Doc item a field (but not an enum constant)? + * + * @return true if it represents a field + */ + @Unused + boolean isField(); + + /** + * Is this Doc item an enum constant? + * + * @return true if it represents an enum constant + * @since 1.5 + */ + @Unused + boolean isEnumConstant(); + + /** + * Is this Doc item a constructor? + * + * @return true if it represents a constructor + */ + @Unused + boolean isConstructor(); + + /** + * Is this Doc item a method (but not a constructor or annotation + * type element)? + * + * @return true if it represents a method + */ + @Unused + boolean isMethod(); + + /** + * Is this Doc item an annotation type element? + * + * @return true if it represents an annotation type element + * @since 1.5 + */ + @Used + boolean isAnnotationTypeElement(); + + /** + * Is this Doc item an interface (but not an annotation type)? + * + * @return true if it represents an interface + */ + @Used + boolean isInterface(); + + /** + * Is this Doc item an exception class? + * + * @return true if it represents an exception + */ + @Used + boolean isException(); + + /** + * Is this Doc item an error class? + * + * @return true if it represents a error + */ + @Used + boolean isError(); + + /** + * Is this Doc item an enum type? + * + * @return true if it represents an enum type + * @since 1.5 + */ + @Used + boolean isEnum(); + + /** + * Is this Doc item an annotation type? + * + * @return true if it represents an annotation type + * @since 1.5 + */ + @Unused + boolean isAnnotationType(); + + /** + * Is this Doc item an + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#class">ordinary + * class</a>? + * (i.e. not an interface, annotation type, enum, exception, or error)? + * + * @return true if it represents an ordinary class + */ + @Used + boolean isOrdinaryClass(); + + /** + * Is this Doc item a + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#class">class</a> + * (and not an interface or annotation type)? + * This includes ordinary classes, enums, errors and exceptions. + * + * @return true if it represents a class + */ + @Unused + boolean isClass(); + + /** + * Return true if this Doc item is + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a> + * in the result set. + */ + @Used + boolean isIncluded(); + + /** + * Return the source position of the first line of the + * corresponding declaration, or null if + * no position is available. A default constructor returns + * null because it has no location in the source file. + * + * @since 1.4 + */ + @Used + SourcePosition position(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/DocErrorReporter.java b/doclet_adapter/src/main/java/com/sun/javadoc/DocErrorReporter.java new file mode 100644 index 0000000..1ce0404 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/DocErrorReporter.java @@ -0,0 +1,91 @@ +/* + * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; + +/** + * This interface provides error, warning and notice printing. + * + * @since 1.2 + * @author Robert Field + */ +public interface DocErrorReporter { + + /** + * Print error message and increment error count. + * + * @param msg message to print + */ + @Unused + void printError(String msg); + + /** + * Print an error message and increment error count. + * + * @param pos the position item where the error occurs + * @param msg message to print + * @since 1.4 + */ + @Unused + void printError(SourcePosition pos, String msg); + + /** + * Print warning message and increment warning count. + * + * @param msg message to print + */ + @Unused + void printWarning(String msg); + + /** + * Print warning message and increment warning count. + * + * @param pos the position item where the warning occurs + * @param msg message to print + * @since 1.4 + */ + @Unused + void printWarning(SourcePosition pos, String msg); + + /** + * Print a message. + * + * @param msg message to print + */ + @Unused + void printNotice(String msg); + + /** + * Print a message. + * + * @param pos the position item where the message occurs + * @param msg message to print + * @since 1.4 + */ + @Unused + void printNotice(SourcePosition pos, String msg); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/ExecutableMemberDoc.java b/doclet_adapter/src/main/java/com/sun/javadoc/ExecutableMemberDoc.java new file mode 100644 index 0000000..61de275 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/ExecutableMemberDoc.java @@ -0,0 +1,164 @@ +/* + * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents a method or constructor of a java class. + * + * @since 1.2 + * @author Robert Field + */ +public interface ExecutableMemberDoc extends MemberDoc { + + /** + * Return exceptions this method or constructor throws. + * If the type of the exception is a type variable, return the + * <code>ClassDoc</code> of its erasure. + * + * <p> <i>The <code>thrownExceptions</code> method cannot + * accommodate certain generic type constructs. The + * <code>thrownExceptionTypes</code> method should be used + * instead.</i> + * + * @return an array of ClassDoc[] representing the exceptions + * thrown by this method. + * @see #thrownExceptionTypes + */ + @Used + ClassDoc[] thrownExceptions(); + + /** + * Return exceptions this method or constructor throws. + * + * @return an array representing the exceptions thrown by this method. + * Each array element is either a <code>ClassDoc</code> or a + * <code>TypeVariable</code>. + * @since 1.5 + */ + @Unused + Type[] thrownExceptionTypes(); + + /** + * Return true if this method is native + */ + @Used + boolean isNative(); + + /** + * Return true if this method is synchronized + */ + @Used + boolean isSynchronized(); + + /** + * Return true if this method was declared to take a variable number + * of arguments. + * + * @since 1.5 + */ + @Used + boolean isVarArgs(); + + /** + * Get argument information. + * + * @see Parameter + * + * @return an array of Parameter, one element per argument + * in the order the arguments are present. + */ + @Used + Parameter[] parameters(); + + /** + * Get the receiver type of this executable element. + * + * @return the receiver type of this executable element. + * @since 1.8 + */ + @Unused + Type receiverType(); + + /** + * Return the throws tags in this method. + * + * @return an array of ThrowTag containing all <code>@exception</code> + * and <code>@throws</code> tags. + */ + @Unused + ThrowsTag[] throwsTags(); + + /** + * Return the param tags in this method, excluding the type + * parameter tags. + * + * @return an array of ParamTag containing all <code>@param</code> tags + * corresponding to the parameters of this method. + */ + @Unused + ParamTag[] paramTags(); + + /** + * Return the type parameter tags in this method. + * + * @return an array of ParamTag containing all <code>@param</code> tags + * corresponding to the type parameters of this method. + * @since 1.5 + */ + @Unused + ParamTag[] typeParamTags(); + + /** + * Get the signature. It is the parameter list, type is qualified. + * For instance, for a method <code>mymethod(String x, int y)</code>, + * it will return <code>(java.lang.String,int)</code>. + */ + @Used + String signature(); + + /** + * get flat signature. all types are not qualified. + * return a String, which is the flat signiture of this member. + * It is the parameter list, type is not qualified. + * For instance, for a method <code>mymethod(String x, int y)</code>, + * it will return <code>(String, int)</code>. + */ + @Used + String flatSignature(); + + /** + * Return the formal type parameters of this method or constructor. + * Return an empty array if this method or constructor is not generic. + * + * @return the formal type parameters of this method or constructor. + * @since 1.5 + */ + @Used + TypeVariable[] typeParameters(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/FieldDoc.java b/doclet_adapter/src/main/java/com/sun/javadoc/FieldDoc.java new file mode 100644 index 0000000..6d8dd9b --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/FieldDoc.java @@ -0,0 +1,88 @@ +/* + * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents a field in a java class. + * + * @see MemberDoc + * + * @since 1.2 + * @author Robert Field + */ +public interface FieldDoc extends MemberDoc { + + /** + * Get type of this field. + */ + @Used + Type type(); + + /** + * Return true if this field is transient + */ + @Used + boolean isTransient(); + + /** + * Return true if this field is volatile + */ + @Used + boolean isVolatile(); + + /** + * Return the serialField tags in this FieldDoc item. + * + * @return an array of <tt>SerialFieldTag</tt> objects containing + * all <code>@serialField</code> tags. + */ + @Unused + SerialFieldTag[] serialFieldTags(); + + /** + * Get the value of a constant field. + * + * @return the value of a constant field. The value is + * automatically wrapped in an object if it has a primitive type. + * If the field is not constant, returns null. + */ + @Used + Object constantValue(); + + /** + * Get the value of a constant field. + * + * @return the text of a Java language expression whose value + * is the value of the constant. The expression uses no identifiers + * other than primitive literals. If the field is + * not constant, returns null. + */ + @Unused + String constantValueExpression(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/MemberDoc.java b/doclet_adapter/src/main/java/com/sun/javadoc/MemberDoc.java new file mode 100644 index 0000000..3be364e --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/MemberDoc.java @@ -0,0 +1,50 @@ +/* + * Copyright (c) 1998, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Used; + +/** + * Represents a member of a java class: field, constructor, or method. + * This is an abstract class dealing with information common to + * method, constructor and field members. Class members of a class + * (innerclasses) are represented instead by ClassDoc. + * + * @see MethodDoc + * @see FieldDoc + * @see ClassDoc + * + * @author Kaiyang Liu (original) + * @author Robert Field (rewrite) + */ +public interface MemberDoc extends ProgramElementDoc { + + /** + * Returns true if this member was synthesized by the compiler. + */ + @Used + boolean isSynthetic(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/MethodDoc.java b/doclet_adapter/src/main/java/com/sun/javadoc/MethodDoc.java new file mode 100644 index 0000000..eceaf40 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/MethodDoc.java @@ -0,0 +1,109 @@ +/* + * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents a method of a java class. + * + * @since 1.2 + * @author Robert Field + */ +public interface MethodDoc extends ExecutableMemberDoc { + + /** + * Return true if this method is abstract + */ + @Used + boolean isAbstract(); + + /** + * Return true if this method is default + */ + @Used + boolean isDefault(); + + /** + * Get return type. + * + * @return the return type of this method, null if it + * is a constructor. + */ + @Used + Type returnType(); + + /** + * Return the class containing the method that this method overrides. + * + * <p> <i>The <code>overriddenClass</code> method cannot + * accommodate certain generic type constructs. The + * <code>overriddenType</code> method should be used instead.</i> + * + * @return a ClassDoc representing the superclass + * defining a method that this method overrides, or null if + * this method does not override. + */ + @Unused + ClassDoc overriddenClass(); + + /** + * Return the type containing the method that this method overrides. + * It may be a <code>ClassDoc</code> or a <code>ParameterizedType</code>. + * + * @return the supertype whose method is overridden, or null if this + * method does not override another in a superclass + * @since 1.5 + */ + @Unused + Type overriddenType(); + + /** + * Return the method that this method overrides. + * + * @return a MethodDoc representing a method definition + * in a superclass this method overrides, null if + * this method does not override. + */ + @Used + MethodDoc overriddenMethod(); + + /** + * Tests whether this method overrides another. + * The overridden method may be one declared in a superclass or + * a superinterface (unlike {@link #overriddenMethod()}). + * + * <p> When a non-abstract method overrides an abstract one, it is + * also said to <i>implement</i> the other. + * + * @param meth the other method to examine + * @return <tt>true</tt> if this method overrides the other + * @since 1.5 + */ + @Unused + boolean overrides(MethodDoc meth); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/PackageDoc.java b/doclet_adapter/src/main/java/com/sun/javadoc/PackageDoc.java new file mode 100644 index 0000000..2a03ddd --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/PackageDoc.java @@ -0,0 +1,142 @@ +/* + * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents a java package. Provides access to information + * about the package, the package's comment and tags, and the + * classes in the package. + * <p> + * Each method whose return type is an array will return an empty + * array (never null) when there are no objects in the result. + * + * @since 1.2 + * @author Kaiyang Liu (original) + * @author Robert Field (rewrite) + */ +public interface PackageDoc extends Doc { + + /** + * Get all classes and interfaces in the package, filtered to the specified + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">access + * modifier option</a>. + * + * @return filtered classes and interfaces in this package + * @param filter Specifying true filters according to the specified access + * modifier option. + * Specifying false includes all classes and interfaces + * regardless of access modifier option. + * @since 1.4 + */ + @Unused + ClassDoc[] allClasses(boolean filter); + + /** + * Get all + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a> + * classes and interfaces in the package. Same as allClasses(true). + * + * @return all included classes and interfaces in this package. + */ + @Unused + ClassDoc[] allClasses(); + + /** + * Get included + * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#class">ordinary</a> + * classes (that is, exclude exceptions, errors, enums, interfaces, and + * annotation types) + * in this package. + * + * @return included ordinary classes in this package. + */ + @Used + ClassDoc[] ordinaryClasses(); + + /** + * Get included Exception classes in this package. + * + * @return included Exceptions in this package. + */ + @Used + ClassDoc[] exceptions(); + + /** + * Get included Error classes in this package. + * + * @return included Errors in this package. + */ + @Used + ClassDoc[] errors(); + + /** + * Get included enum types in this package. + * + * @return included enum types in this package. + * @since 1.5 + */ + @Used + ClassDoc[] enums(); + + /** + * Get included interfaces in this package, omitting annotation types. + * + * @return included interfaces in this package. + */ + @Used + ClassDoc[] interfaces(); + + /** + * Get included annotation types in this package. + * + * @return included annotation types in this package. + * @since 1.5 + */ + @Used + AnnotationTypeDoc[] annotationTypes(); + + /** + * Get the annotations of this package. + * Return an empty array if there are none. + * + * @return the annotations of this package. + * @since 1.5 + */ + @Unused + AnnotationDesc[] annotations(); + + /** + * Lookup a class or interface within this package. + * + * @return ClassDoc of found class or interface, + * or null if not found. + */ + @Unused + ClassDoc findClass(String className); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/ParamTag.java b/doclet_adapter/src/main/java/com/sun/javadoc/ParamTag.java new file mode 100644 index 0000000..58c3ec7 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/ParamTag.java @@ -0,0 +1,72 @@ +/* + * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Used; + +/** + * Represents an @param documentation tag. + * Stores the name and comment parts of the parameter tag. + * An @param tag may represent either a method or constructor parameter, + * or a type parameter. + * + * @author Robert Field + * + */ +public interface ParamTag extends Tag { + + /** + * Return the name of the parameter or type parameter + * associated with this <code>ParamTag</code>. + * The angle brackets delimiting a type parameter are not part of + * its name. + * + * @return the parameter name. + */ + @Used + String parameterName(); + + /** + * Return the parameter comment + * associated with this <code>ParamTag</code>. + * + * @return the parameter comment. + */ + @Used + String parameterComment(); + + /** + * Return true if this <code>ParamTag</code> corresponds to a type + * parameter. Return false if it corresponds to an ordinary parameter + * of a method or constructor. + * + * @return true if this <code>ParamTag</code> corresponds to a type + * parameter. + * @since 1.5 + */ + @Used + boolean isTypeParameter(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/Parameter.java b/doclet_adapter/src/main/java/com/sun/javadoc/Parameter.java new file mode 100644 index 0000000..facfbab --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/Parameter.java @@ -0,0 +1,82 @@ +/* + * Copyright (c) 1998, 2004, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Parameter information. + * This includes a parameter type and parameter name. + * + * @author Robert Field + */ +public interface Parameter { + + /** + * Get the type of this parameter. + */ + @Used + Type type(); + + /** + * Get local name of this parameter. + * For example if parameter is the short 'index', returns "index". + */ + @Used + String name(); + + /** + * Get type name of this parameter. + * For example if parameter is the short 'index', returns "short". + * <p> + * This method returns a complete string + * representation of the type, including the dimensions of arrays and + * the type arguments of parameterized types. Names are qualified. + */ + @Used + String typeName(); + + /** + * Returns a string representation of the parameter. + * <p> + * For example if parameter is the short 'index', returns "short index". + * + * @return type and parameter name of this parameter. + */ + @Unused + String toString(); + + /** + * Get the annotations of this parameter. + * Return an empty array if there are none. + * + * @return the annotations of this parameter. + * @since 1.5 + */ + @Used + AnnotationDesc[] annotations(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/ParameterizedType.java b/doclet_adapter/src/main/java/com/sun/javadoc/ParameterizedType.java new file mode 100644 index 0000000..1435175 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/ParameterizedType.java @@ -0,0 +1,116 @@ +/* + * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents an invocation of a generic class or interface. For example, + * given the generic interface {@code List<E>}, possible invocations + * include: + * <pre> + * {@code List<String>} + * {@code List<T extends Number>} + * {@code List<?>} + * </pre> + * A generic inner class {@code Outer<T>.Inner<S>} might be invoked as: + * <pre> + * {@code Outer<Number>.Inner<String>} + * </pre> + * + * @author Scott Seligman + * @since 1.5 + */ +public interface ParameterizedType extends Type { + + /** + * Return the generic class or interface that declared this type. + * + * @return the generic class or interface that declared this type. + */ + @Unused + ClassDoc asClassDoc(); + + /** + * Return the actual type arguments of this type. + * For a generic type that is nested within some other generic type + * (such as {@code Outer<T>.Inner<S>}), + * only the type arguments of the innermost type are included. + * + * @return the actual type arguments of this type. + */ + @Used + Type[] typeArguments(); + + /** + * Return the class type that is a direct supertype of this one. + * This is the superclass of this type's declaring class, + * with type arguments substituted in. + * Return null if this is an interface type. + * + * <p> For example, if this parameterized type is + * {@code java.util.ArrayList<String>}, the result will be + * {@code java.util.AbstractList<String>}. + * + * @return the class type that is a direct supertype of this one. + */ + @Unused + Type superclassType(); + + /** + * Return the interface types directly implemented by or extended by this + * parameterized type. + * These are the interfaces directly implemented or extended + * by this type's declaring class or interface, + * with type arguments substituted in. + * Return an empty array if there are no interfaces. + * + * <p> For example, the interface extended by + * {@code java.util.Set<String>} is {@code java.util.Collection<String>}. + * + * @return the interface types directly implemented by or extended by this + * parameterized type. + */ + @Unused + Type[] interfaceTypes(); + + /** + * Return the type that contains this type as a member. + * Return null is this is a top-level type. + * + * <p> For example, the containing type of + * {@code AnInterface.Nested<Number>} is the <code>ClassDoc</code> + * representing {@code AnInterface}, and the containing type of + * {@code Outer<String>.Inner<Number>} is the + * <code>ParameterizedType</code> representing {@code Outer<String>}. + * + * @return the type that contains this type as a member. + */ + @Unused + Type containingType(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/ProgramElementDoc.java b/doclet_adapter/src/main/java/com/sun/javadoc/ProgramElementDoc.java new file mode 100644 index 0000000..f6f293b --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/ProgramElementDoc.java @@ -0,0 +1,140 @@ +/* + * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents a java program element: class, interface, field, + * constructor, or method. + * This is an abstract class dealing with information common to + * these elements. + * + * @see MemberDoc + * @see ClassDoc + * + * @author Robert Field + */ +public interface ProgramElementDoc extends Doc { + + /** + * Get the containing class or interface of this program element. + * + * @return a ClassDoc for this element's containing class or interface. + * If this is a top-level class or interface, return null. + */ + @Used + ClassDoc containingClass(); + + /** + * Get the package that this program element is contained in. + * + * @return a PackageDoc for this element containing package. + * If in the unnamed package, this PackageDoc will have the + * name "". + */ + @Used + PackageDoc containingPackage(); + + /** + * Get the fully qualified name of this program element. + * For example, for the class <code>java.util.Hashtable</code>, + * return "java.util.Hashtable". + * <p> + * For the method <code>bar()</code> in class <code>Foo</code> + * in the unnamed package, return "Foo.bar". + * + * @return the qualified name of the program element as a String. + */ + @Used + String qualifiedName(); + + /** + * Get the modifier specifier integer. + * + * @see java.lang.reflect.Modifier + */ + @Unused + int modifierSpecifier(); + + /** + * Get modifiers string. + * For example, for: + * <pre> + * public abstract int foo() { ... } + * </pre> + * return "public abstract". + * Annotations are not included. + */ + @Unused + String modifiers(); + + /** + * Get the annotations of this program element. + * Return an empty array if there are none. + * + * @return the annotations of this program element. + * @since 1.5 + */ + @Used + AnnotationDesc[] annotations(); + + /** + * Return true if this program element is public. + */ + @Used + boolean isPublic(); + + /** + * Return true if this program element is protected. + */ + @Used + boolean isProtected(); + + /** + * Return true if this program element is private. + */ + @Used + boolean isPrivate(); + + /** + * Return true if this program element is package private. + */ + @Used + boolean isPackagePrivate(); + /** + * Return true if this program element is static. + */ + @Used + boolean isStatic(); + + /** + * Return true if this program element is final. + */ + @Used + boolean isFinal(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/RootDoc.java b/doclet_adapter/src/main/java/com/sun/javadoc/RootDoc.java new file mode 100644 index 0000000..fc09a95 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/RootDoc.java @@ -0,0 +1,118 @@ +/* + * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents the root of the program structure information + * for one run of javadoc. From this root all other program + * structure information can be extracted. + * Also represents the command line information -- the + * packages, classes and options specified by the user. + * + * @since 1.2 + * @author Robert Field + */ +public interface RootDoc extends Doc, DocErrorReporter { + + /** + * Command line options. + * <p> + * For example, given: + * <pre> + * javadoc -foo this that -bar other ...</pre> + * + * this method will return: + * <pre> + * options()[0][0] = "-foo" + * options()[0][1] = "this" + * options()[0][2] = "that" + * options()[1][0] = "-bar" + * options()[1][1] = "other"</pre> + * + * @return an array of arrays of String. + */ + @Unused + String[][] options(); + + /** + * Return the packages + * <a href="package-summary.html#included">specified</a> + * on the command line. + * If <code>-subpackages</code> and <code>-exclude</code> options + * are used, return all the non-excluded packages. + * + * @return packages specified on the command line. + */ + @Unused + PackageDoc[] specifiedPackages(); + + /** + * Return the classes and interfaces + * <a href="package-summary.html#included">specified</a> + * as source file names on the command line. + * + * @return classes and interfaces specified on the command line. + */ + @Unused + ClassDoc[] specifiedClasses(); + + /** + * Return the + * <a href="package-summary.html#included">included</a> + classes and interfaces in all packages. + * + * @return included classes and interfaces in all packages. + */ + @Used + ClassDoc[] classes(); + + /** + * Return a PackageDoc for the specified package name. + * + * @param name package name + * + * @return a PackageDoc holding the specified package, null if + * this package is not referenced. + */ + @Used + PackageDoc packageNamed(String name); + + /** + * Return a ClassDoc for the specified class or interface name. + * + * @param qualifiedName + * <a href="package-summary.html#qualified">qualified</a> + * class or package name + * + * @return a ClassDoc holding the specified class, null if + * this class is not referenced. + */ + @Used + ClassDoc classNamed(String qualifiedName); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/SeeTag.java b/doclet_adapter/src/main/java/com/sun/javadoc/SeeTag.java new file mode 100644 index 0000000..e0c8269 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/SeeTag.java @@ -0,0 +1,134 @@ +/* + * Copyright (c) 1998, 2002, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; + +/** + * Represents a user-defined cross-reference to related documentation. + * The tag can reference a package, class or member, or can hold + * plain text. (The plain text might be a reference + * to something not online, such as a printed book, or be a hard-coded + * HTML link.) The reference can either be inline with the comment, + * using <code>{@link}</code>, or a separate block comment, + * using <code>@see</code>. + * Method <code>name()</code> returns "@link" (no curly braces) or + * "@see", depending on the tag. + * Method <code>kind()</code> returns "@see" for both tags. + * + * @author Kaiyang Liu (original) + * @author Robert Field (rewrite) + * @author Atul M Dambalkar + * + */ +public interface SeeTag extends Tag { + + /** + * Get the label of the <code>@see</code> tag. + * Return null if no label is present. + * For example, for: + * <p> + * <code>@see String#trim() the trim method</code> + * </p> + * return "the trim method". + */ + @Unused + String label(); + + /** + * Get the package doc when <code>@see</code> references only a package. + * Return null if the package cannot be found, or if + * <code>@see</code> references any other element (class, + * interface, field, constructor, method) or non-element. + * For example, for: + * <p> + * <code>@see java.lang</code> + * </p> + * return the <code>PackageDoc</code> for <code>java.lang</code>. + */ + @Unused + PackageDoc referencedPackage(); + + /** + * Get the class or interface name of the <code>@see</code> reference. + * The name is fully qualified if the name specified in the + * original <code>@see</code> tag was fully qualified, or if the class + * or interface can be found; otherwise it is unqualified. + * If <code>@see</code> references only a package name, then return + * the package name instead. + * For example, for: + * <p> + * <code>@see String#valueOf(java.lang.Object)</code> + * </p> + * return "java.lang.String". + * For "<code>@see java.lang</code>", return "java.lang". + * Return null if <code>@see</code> references a non-element, such as + * <code>@see <a href="java.sun.com"></code>. + */ + @Unused + String referencedClassName(); + + /** + * Get the class doc referenced by the class name part of @see. + * Return null if the class cannot be found. + * For example, for: + * <p> + * <code>@see String#valueOf(java.lang.Object)</code> + * </p> + * return the <code>ClassDoc</code> for <code>java.lang.String</code>. + */ + @Unused + ClassDoc referencedClass(); + + /** + * Get the field, constructor or method substring of the <code>@see</code> + * reference. Return null if the reference is to any other + * element or to any non-element. + * References to member classes (nested classes) return null. + * For example, for: + * <p> + * <code>@see String#startsWith(String)</code> + * </p> + * return "startsWith(String)". + */ + @Unused + String referencedMemberName(); + + /** + * Get the member doc for the field, constructor or method + * referenced by <code>@see</code>. Return null if the member cannot + * be found or if the reference is to any other element or to any + * non-element. + * References to member classes (nested classes) return null. + * For example, for: + * <p> + * <code>@see String#startsWith(java.lang.String)</code> + * </p> + * return the <code>MethodDoc</code> for <code>startsWith</code>. + */ + @Unused + MemberDoc referencedMember(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/SerialFieldTag.java b/doclet_adapter/src/main/java/com/sun/javadoc/SerialFieldTag.java new file mode 100644 index 0000000..54ac120 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/SerialFieldTag.java @@ -0,0 +1,93 @@ +/* + * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; + +/** + * Documents a Serializable field defined by an ObjectStreamField. + * <pre> + * The class parses and stores the three serialField tag parameters: + * + * - field name + * - field type name + * (fully-qualified or visible from the current import context) + * - description of the valid values for the field + + * </pre> + * This tag is only allowed in the javadoc for the special member + * serialPersistentFields. + * + * @author Joe Fialli + * + * @see java.io.ObjectStreamField + */ +public interface SerialFieldTag extends Tag, Comparable<Object> { + + /** + * Return the serializable field name. + */ + @Unused + String fieldName(); + + /** + * Return the field type string. + */ + @Unused + String fieldType(); + + /** + * Return the ClassDoc for field type. + * + * @return null if no ClassDoc for field type is visible from + * containingClass context. + */ + @Unused + ClassDoc fieldTypeDoc(); + + /** + * Return the field comment. If there is no serialField comment, return + * javadoc comment of corresponding FieldDoc. + */ + @Unused + String description(); + + /** + * Compares this Object with the specified Object for order. Returns a + * negative integer, zero, or a positive integer as this Object is less + * than, equal to, or greater than the given Object. + * <p> + * Included to make SerialFieldTag items java.lang.Comparable. + * + * @param obj the <code>Object</code> to be compared. + * @return a negative integer, zero, or a positive integer as this Object + * is less than, equal to, or greater than the given Object. + * @exception ClassCastException the specified Object's type prevents it + * from being compared to this Object. + * @since 1.2 + */ + int compareTo(Object obj); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/SourcePosition.java b/doclet_adapter/src/main/java/com/sun/javadoc/SourcePosition.java new file mode 100644 index 0000000..27f1acd --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/SourcePosition.java @@ -0,0 +1,61 @@ +/* + * Copyright (c) 2001, 2002, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import java.io.File; + +/** + * This interface describes a source position: filename, line number, + * and column number. + * + * @since 1.4 + * @author Neal M Gafter + */ +public interface SourcePosition { + /** The source file. Returns null if no file information is + * available. */ + @Used + File file(); + + /** The line in the source file. The first line is numbered 1; + * 0 means no line number information is available. */ + @Used + int line(); + + /** The column in the source file. The first column is + * numbered 1; 0 means no column information is available. + * Columns count characters in the input stream; a tab + * advances the column number to the next 8-column tab stop. + */ + @Used + int column(); + + /** Convert the source position to the form "Filename:line". */ + @Unused + String toString(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/Tag.java b/doclet_adapter/src/main/java/com/sun/javadoc/Tag.java new file mode 100644 index 0000000..2a1d4d8 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/Tag.java @@ -0,0 +1,176 @@ +/* + * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; +import java.text.BreakIterator; +import java.util.Locale; + +/** + * Represents a simple documentation tag, such as @since, @author, @version. + * Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since") + * and tag text (e.g. "1.2"). Tags with structure or which require + * special processing are handled by subclasses such as ParamTag + * (for @param), SeeTag (for @see and {@link}), and ThrowsTag + * (for @throws). + * + * @author Robert Field + * @author Atul M Dambalkar + * @see SeeTag + * @see ParamTag + * @see ThrowsTag + * @see SerialFieldTag + * @see Doc#tags() + * + */ +public interface Tag { + + /** + * Return the name of this tag. The name is the string + * starting with "@" that is used in a doc comment, such as + * <code>@return</code>. For inline tags, such as + * <code>{@link}</code>, the curly brackets + * are not part of the name, so in this example the name + * would be simply <code>@link</code>. + * + * @return the name of this tag + */ + @Used + String name(); + + /** + * Return the containing {@link Doc} of this Tag element. + * + * @return the containing {@link Doc} of this Tag element + */ + @Unused + Doc holder(); + + /** + * Return the kind of this tag. + * For most tags, + * <code>kind() == name()</code>; + * the following table lists those cases where there is more + * than one tag of a given kind: + * + * <table border="1" cellpadding="4" cellspacing="0" summary="related tags"> + * <tr><th>{@code kind() }</th> <th>{@code name() }</th></tr> + * <tr><td>{@code @throws }</td> <td>{@code @throws }</td></tr> + * <tr><td>{@code @throws }</td> <td>{@code @exception }</td></tr> + * <tr><td>{@code @see }</td> <td>{@code @see }</td></tr> + * <tr><td>{@code @see }</td> <td>{@code @link }</td></tr> + * <tr><td>{@code @see }</td> <td>{@code @linkplain }</td></tr> + * <tr><td>{@code @serial }</td> <td>{@code @serial }</td></tr> + * <tr><td>{@code @serial }</td> <td>{@code @serialData }</td></tr> + * </table> + * + * @return the kind of this tag. + */ + @Used + String kind(); + + /** + * Return the text of this tag, that is, the portion beyond tag name. + * + * @return the text of this tag + */ + @Used + String text(); + + /** + * Convert this object to a string. + */ + @Unused + String toString(); + + /** + * For a documentation comment with embedded <code>{@link}</code> + * tags, return an array of <code>Tag</code> objects. The entire + * doc comment is broken down into strings separated by + * <code>{@link}</code> tags, where each successive element + * of the array represents either a string or + * <code>{@link}</code> tag, in order, from start to end. + * Each string is represented by a <code>Tag</code> object of + * name "Text", where {@link #text()} returns the string. Each + * <code>{@link}</code> tag is represented by a + * {@link SeeTag} of name "@link" and kind "@see". + * For example, given the following comment + * tag: + * <p> + * <code>This is a {@link Doc commentlabel} example.</code> + * <p> + * return an array of Tag objects: + * <ul> + * <li> tags[0] is a {@link Tag} with name "Text" and text consisting + * of "This is a " + * <li> tags[1] is a {@link SeeTag} with name "@link", referenced + * class <code>Doc</code> and label "commentlabel" + * <li> tags[2] is a {@link Tag} with name "Text" and text consisting + * of " example." + * </ul> + * + * @return Tag[] array of tags + * @see ParamTag + * @see ThrowsTag + */ + @Unused + Tag[] inlineTags(); + + /** + * Return the first sentence of the comment as an array of tags. + * Includes inline tags + * (i.e. {@link <i>reference</i>} tags) but not + * block tags. + * Each section of plain text is represented as a {@link Tag} + * of kind "Text". + * Inline tags are represented as a {@link SeeTag} of kind "@link". + * If the locale is English language, the first sentence is + * determined by the rules described in the Java Language + * Specification (first version): "This sentence ends + * at the first period that is followed by a blank, tab, or + * line terminator or at the first tagline.", in + * addition a line will be terminated by paragraph and + * section terminating HTML tags: <p> </p> <h1> + * <h2> <h3> <h4> <h5> <h6> + * <hr> <pre> or </pre>. + * If the locale is not English, the sentence end will be + * determined by + * {@link BreakIterator#getSentenceInstance(Locale)}. + * + * @return an array of {@link Tag} objects representing the + * first sentence of the comment + */ + @Unused + Tag[] firstSentenceTags(); + + /** + * Return the source position of this tag. + * @return the source position of this tag. + */ + @Used + SourcePosition position(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/ThrowsTag.java b/doclet_adapter/src/main/java/com/sun/javadoc/ThrowsTag.java new file mode 100644 index 0000000..b24af85 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/ThrowsTag.java @@ -0,0 +1,86 @@ +/* + * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents a @throws or @exception documentation tag. + * Parses and holds the exception name and exception comment. + * Note: @exception is a backwards compatible synonymy for @throws. + * + * @author Robert Field + * @author Atul M Dambalkar + * @see ExecutableMemberDoc#throwsTags() + * + */ +public interface ThrowsTag extends Tag { + + /** + * Return the name of the exception + * associated with this <code>ThrowsTag</code>. + * + * @return name of the exception. + */ + @Unused + String exceptionName(); + + /** + * Return the exception comment + * associated with this <code>ThrowsTag</code>. + * + * @return exception comment. + */ + @Used + String exceptionComment(); + + /** + * Return a <code>ClassDoc</code> that represents the exception. + * If the type of the exception is a type variable, return the + * <code>ClassDoc</code> of its erasure. + * + * <p> <i>This method cannot accommodate certain generic type + * constructs. The <code>exceptionType</code> method + * should be used instead.</i> + * + * @return <code>ClassDoc</code> that represents the exception. + * @see #exceptionType + */ + @Used + ClassDoc exception(); + + /** + * Return the type of the exception + * associated with this <code>ThrowsTag</code>. + * This may be a <code>ClassDoc</code> or a <code>TypeVariable</code>. + * + * @return the type of the exception. + * @since 1.5 + */ + @Unused + Type exceptionType(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/Type.java b/doclet_adapter/src/main/java/com/sun/javadoc/Type.java new file mode 100644 index 0000000..207dfc4 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/Type.java @@ -0,0 +1,188 @@ +/* + * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents a type. A type can be a class or interface, an + * invocation (like {@code List<String>}) of a generic class or interface, + * a type variable, a wildcard type ("<code>?</code>"), + * or a primitive data type (like <code>char</code>). + * + * @since 1.2 + * @author Kaiyang Liu (original) + * @author Robert Field (rewrite) + * @author Scott Seligman (generics) + */ +public interface Type { + + /** + * Return unqualified name of type excluding any dimension information. + * <p> + * For example, a two dimensional array of String returns + * "<code>String</code>". + */ + @Unused + String typeName(); + + /** + * Return qualified name of type excluding any dimension information. + *<p> + * For example, a two dimensional array of String + * returns "<code>java.lang.String</code>". + */ + @Used + String qualifiedTypeName(); + + /** + * Return the simple name of this type excluding any dimension information. + * This is the unqualified name of the type, except that for nested types + * only the identifier of the innermost type is included. + * <p> + * For example, the class {@code Outer.Inner} returns + * "<code>Inner</code>". + * + * @since 1.5 + */ + @Used + String simpleTypeName(); + + /** + * Return the type's dimension information, as a string. + * <p> + * For example, a two dimensional array of String returns + * "<code>[][]</code>". + */ + @Used + String dimension(); + + /** + * Return a string representation of the type. + * This includes any dimension information and type arguments. + * <p> + * For example, a two dimensional array of String may return + * "<code>java.lang.String[][]</code>", + * and the parameterized type {@code List<Integer>} may return + * "{@code java.util.List<java.lang.Integer>}". + * + * @return a string representation of the type. + */ + @Used + String toString(); + + /** + * Return true if this type represents a primitive type. + * + * @return true if this type represents a primitive type. + * @since 1.5 + */ + @Used + boolean isPrimitive(); + + /** + * Return this type as a <code>ClassDoc</code> if it represents a class + * or interface. Array dimensions are ignored. + * If this type is a <code>ParameterizedType</code>, + * <code>TypeVariable</code>, or <code>WildcardType</code>, return + * the <code>ClassDoc</code> of the type's erasure. If this is an + * <code>AnnotationTypeDoc</code>, return this as a <code>ClassDoc</code> + * (but see {@link #asAnnotationTypeDoc()}). + * If this is a primitive type, return null. + * + * @return the <code>ClassDoc</code> of this type, + * or null if it is a primitive type. + */ + @Used + ClassDoc asClassDoc(); + + /** + * Return this type as a <code>ParameterizedType</code> if it represents + * an invocation of a generic class or interface. Array dimensions + * are ignored. + * + * @return a <code>ParameterizedType</code> if the type is an + * invocation of a generic type, or null if it is not. + * @since 1.5 + */ + @Used + ParameterizedType asParameterizedType(); + + /** + * Return this type as a <code>TypeVariable</code> if it represents + * a type variable. Array dimensions are ignored. + * + * @return a <code>TypeVariable</code> if the type is a type variable, + * or null if it is not. + * @since 1.5 + */ + @Used + TypeVariable asTypeVariable(); + + /** + * Return this type as a <code>WildcardType</code> if it represents + * a wildcard type. + * + * @return a <code>WildcardType</code> if the type is a wildcard type, + * or null if it is not. + * @since 1.5 + */ + @Used + WildcardType asWildcardType(); + + /** + * Returns this type as a <code>AnnotatedType</code> if it represents + * an annotated type. + * + * @return a <code>AnnotatedType</code> if the type if an annotated type, + * or null if it is not + * @since 1.8 + */ + @Used + AnnotatedType asAnnotatedType(); + + /** + * Return this type as an <code>AnnotationTypeDoc</code> if it represents + * an annotation type. Array dimensions are ignored. + * + * @return an <code>AnnotationTypeDoc</code> if the type is an annotation + * type, or null if it is not. + * @since 1.5 + */ + @Unused + AnnotationTypeDoc asAnnotationTypeDoc(); + + /** + * If this type is an array type, return the element type of the + * array. Otherwise, return null. + * + * @return a <code>Type</code> representing the element type or null. + * @since 1.8 + */ + @Unused + Type getElementType(); +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/TypeVariable.java b/doclet_adapter/src/main/java/com/sun/javadoc/TypeVariable.java new file mode 100644 index 0000000..2d8db2e --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/TypeVariable.java @@ -0,0 +1,71 @@ +/* + * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + + +import com.google.doclava.annotation.Unused; +import com.google.doclava.annotation.Used; + +/** + * Represents a type variable. + * For example, the generic interface {@code List<E>} has a single + * type variable {@code E}. + * A type variable may have explicit bounds, as in + * {@code C<R extends Remote>}. + * + * @author Scott Seligman + * @since 1.5 + */ +public interface TypeVariable extends Type { + + /** + * Return the bounds of this type variable. + * These are the types given by the <i>extends</i> clause. + * Return an empty array if there are no explicit bounds. + * + * @return the bounds of this type variable. + */ + @Used + Type[] bounds(); + + /** + * Return the class, interface, method, or constructor within + * which this type variable is declared. + * + * @return the class, interface, method, or constructor within + * which this type variable is declared. + */ + @Unused + ProgramElementDoc owner(); + + /** + * Get the annotations of this program element. + * Return an empty array if there are none. + */ + @Unused + AnnotationDesc[] annotations(); + +} diff --git a/doclet_adapter/src/main/java/com/sun/javadoc/WildcardType.java b/doclet_adapter/src/main/java/com/sun/javadoc/WildcardType.java new file mode 100644 index 0000000..0178463 --- /dev/null +++ b/doclet_adapter/src/main/java/com/sun/javadoc/WildcardType.java @@ -0,0 +1,65 @@ +/* + * Copyright (c) 2003, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package com.sun.javadoc; + + +import com.google.doclava.annotation.Used; + +/** + * Represents a wildcard type argument. + * Examples include: <pre> + * {@code <?>} + * {@code <? extends E>} + * {@code <? super T>} + * </pre> + * A wildcard type can have explicit <i>extends</i> bounds + * or explicit <i>super</i> bounds or neither, but not both. + * + * @author Scott Seligman + * @since 1.5 + */ +public interface WildcardType extends Type { + + /** + * Return the upper bounds of this wildcard type argument + * as given by the <i>extends</i> clause. + * Return an empty array if no such bounds are explicitly given. + * + * @return the extends bounds of this wildcard type argument + */ + @Used + Type[] extendsBounds(); + + /** + * Return the lower bounds of this wildcard type argument + * as given by the <i>super</i> clause. + * Return an empty array if no such bounds are explicitly given. + * + * @return the super bounds of this wildcard type argument + */ + @Used + Type[] superBounds(); +} |