Improve javadoc of several methods, especially Type.name()

core/src/main/java/org/jboss/jandex/ClassInfo.java

@@ -222,21 +222,26 @@ public final Kind kind() {
         return Kind.CLASS;
     }
 
+    /**
+     * Returns the binary name of this class.
+     *
+     * @return the binary name of this class
+     */
     public String toString() {
         return name.toString();
     }
 
     /**
-     * Returns the name of the class
+     * Returns the binary name of the class as a {@link DotName}.
      *
-     * @return the name of the class
+     * @return the binary name of the class as a {@link DotName}
      */
     public final DotName name() {
         return name;
     }
 
     /**
-     * Returns the access flags for this class. The standard {@link java.lang.reflect.Modifier}
+     * Returns the access flags for this class. The {@link java.lang.reflect.Modifier} methods
      * can be used to decode the value.
      *
      * @return the access flags

core/src/main/java/org/jboss/jandex/FieldInfo.java

@@ -384,8 +384,8 @@ public int enumConstantOrdinal() {
     }
 
     /**
-     * Returns a string representation describing this field. It is similar although not necessarily identical
-     * to a Java source code expression representing this field.
+     * Returns a string representation describing this field. It is similar although not
+     * necessarily identical to a Java source code declaration of this field.
      *
      * @return a string representation of this field
      */

core/src/main/java/org/jboss/jandex/MethodInfo.java

@@ -587,10 +587,10 @@ public boolean isConstructor() {
     }
 
     /**
-     * Returns a string representation describing this field. It is similar although not
-     * necessarily identical to a Java source code expression representing this field.
+     * Returns a string representation describing this method. It is similar although not
+     * necessarily identical to a Java source code declaration of this method.
      *
-     * @return a string representation for this field
+     * @return a string representation of this method
      */
     public String toString() {
         return methodInternal.toString();

core/src/main/java/org/jboss/jandex/MethodParameterInfo.java

@@ -331,9 +331,10 @@ public List<AnnotationInstance> declaredAnnotations() {
     }
 
     /**
-     * Returns a string representation describing this method parameter
+     * Returns a string representation describing this method parameter. It is similar although not
+     * necessarily identical to a Java source code declaration of this method parameter.
      *
-     * @return a string representation of this parameter
+     * @return a string representation of this method parameter
      */
     public String toString() {
         return method + " #" + position;

core/src/main/java/org/jboss/jandex/RecordComponentInfo.java

@@ -319,7 +319,8 @@ public final List<AnnotationInstance> declaredAnnotations() {
     }
 
     /**
-     * Returns a string representation describing this record component.
+     * Returns a string representation describing this record component. It is similar although not
+     * necessarily identical to a Java source code declaration of this record component.
      *
      * @return a string representation of this record component
      */

core/src/main/java/org/jboss/jandex/Type.java

@@ -202,16 +202,28 @@ public static Type createWithAnnotations(DotName name, Kind kind, AnnotationInst
     }
 
     /**
-     * Returns the raw name of this type. Primitives and void are returned as the
-     * Java keyword (void, boolean, byte, short, int, long, float, double, char).
-     * Arrays are returned using the Java reflection array syntax (e.g.
-     * {@code [[[Ljava.lang.String;}) Classes are returned as a normal {@code DotName}.
-     * <p>
-     * Generic values are returned as the underlying raw value. For example,
-     * a wildcard such as {@code ? extends Number} has a raw type of
-     * {@code Number}.
+     * Returns the name of this type (or its erasure in case of generic types) as a {@link DotName},
+     * using the {@link Class#getName()} format. Specifically:
+     * <ul>
+     * <li>for primitive types and the void pseudo-type, the corresponding Java keyword
+     * is returned ({@code void}, {@code boolean}, {@code byte}, {@code short}, {@code int},
+     * {@code long}, {@code float}, {@code double}, {@code char});
+     * <li>for class types, the binary name of the class is returned;</li>
+     * <li>for array types, a string is returned that consists of one or more {@code [}
+     * characters corresponding to the number of dimensions of the array type,
+     * followed by the element type as a single-character code for primitive types
+     * or {@code L<binary class name>;} for class types (for example, {@code [I} for {@code int[]}
+     * or {@code [[Ljava.lang.String;} for {@code String[][]});</li>
+     * <li>for parameterized types, the binary name of the generic class is returned
+     * (for example, {@code java.util.List} for {@code List<String>});</li>
+     * <li>for type variables, the name of the first bound of the type variable is returned,
+     * or {@code java.lang.Object} for type variables that have no bound;</li>
+     * <li>for wildcard types, the name of the upper bound is returned,
+     * or {@code java.lang.Object} if the wildcard type does not have an upper bound
+     * (for example, {@code java.lang.Number} for {@code ? extends Number}).</li>
+     * </ul>
      *
-     * @return the name of this type
+     * @return the name of this type (or its erasure in case of generic types)
      */
     public DotName name() {
         return name;