archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 06:45:07 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8342466: Improve API documentation for java.lang.classfile.attribute

Browse source 
Reviewed-by: darcy, asotona
This commit is contained in:
Chen Liang 2025-01-15 02:04:01 +00:00
parent 9782bfdd27
commit 973c630777
70 changed files with 2443 additions and 967 deletions
Download patch file Download diff file Expand all files Collapse all files

77
src/java.base/share/classes/java/lang/classfile/MethodSignature.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2022, 2025, 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
@ -24,7 +24,10 @@
*/
package java.lang.classfile;
import java.lang.classfile.attribute.SignatureAttribute;
import java.lang.constant.MethodTypeDesc;
import java.lang.reflect.Executable;
import java.lang.reflect.Method;
import java.util.List;
import jdk.internal.classfile.impl.SignaturesImpl;
@ -33,34 +36,68 @@ import jdk.internal.classfile.impl.Util;
import static java.util.Objects.requireNonNull;
/**
* Models the generic signature of a method, as defined by JVMS {@jvms 4.7.9}.
* Models the generic signature of a method or constructor, as defined by JVMS
* {@jvms 4.7.9.1}.
*
* @see Executable
* @see SignatureAttribute
* @jls 8.4 Method Declarations
* @jls 8.8 Constructor Declarations
* @jvms 4.7.9.1 Signatures
* @since 24
*/
public sealed interface MethodSignature
permits SignaturesImpl.MethodSignatureImpl {
/** {@return the type parameters of this method} */
/**
* {@return the type parameters of this method or constructor, may be empty}
*
* @see Executable#getTypeParameters()
* @jls 8.4.4 Generic Methods
* @jls 8.8.4 Generic Constructors
*/
List<Signature.TypeParam> typeParameters();
/** {@return the signatures of the parameters of this method} */
/**
* {@return the signatures of the parameters of this method or constructor,
* may be empty} The parameters may differ from those in the method
* descriptor because some synthetic or implicit parameters are omitted.
*
* @see Executable#getGenericParameterTypes()
* @jls 8.4.1 Formal Parameters
* @jls 8.8.1 Formal Parameters
*/
List<Signature> arguments();
/** {@return the signatures of the return value of this method} */
/**
* {@return the signatures of the return value of this method} For
* constructors, this returns a signature representing {@code void}.
*
* @see Method#getGenericReturnType()
* @jls 8.4.5 Method Result
*/
Signature result();
/** {@return the signatures of the exceptions thrown by this method} */
/**
* {@return the signatures of the exceptions thrown by this method or
* constructor}
*
* @see Executable#getGenericExceptionTypes()
* @jls 8.4.6 Method Throws
* @jls 8.8.5 Constructor Throws
*/
List<Signature.ThrowableSig> throwableSignatures();
/** {@return the raw signature string} */
String signatureString();
/**
* {@return a method signature for a raw (no generic information) method descriptor}
* {@return a method signature for a raw method descriptor} The resulting
* signature has no type parameter or exception type declared.
*
* @param methodDescriptor the method descriptor
*/
public static MethodSignature of(MethodTypeDesc methodDescriptor) {
requireNonNull(methodDescriptor);
return new SignaturesImpl.MethodSignatureImpl(
List.of(),
@ -70,13 +107,15 @@ public sealed interface MethodSignature
}
/**
* {@return a method signature}
* {@return a method signature with no type parameter or exception type}
* The parameters may differ from those in the method descriptor because
* some synthetic or implicit parameters are omitted.
*
* @param result signature for the return type
* @param arguments signatures for the method arguments
* @param arguments signatures for the method parameters
*/
public static MethodSignature of(Signature result,
Signature... arguments) {
return new SignaturesImpl.MethodSignatureImpl(List.of(),
List.of(),
requireNonNull(result),
@ -84,17 +123,19 @@ public sealed interface MethodSignature
}
/**
* {@return a method signature}
* {@return a method signature} The parameters may differ from those in
* the method descriptor because some synthetic or implicit parameters are
* omitted.
*
* @param typeParameters signatures for the type parameters
* @param exceptions signatures for the exceptions
* @param result signature for the return type
* @param arguments signatures for the method arguments
* @param arguments signatures for the method parameters
*/
public static MethodSignature of(List<Signature.TypeParam> typeParameters,
List<Signature.ThrowableSig> exceptions,
Signature result,
Signature... arguments) {
return new SignaturesImpl.MethodSignatureImpl(
List.copyOf(requireNonNull(typeParameters)),
List.copyOf(requireNonNull(exceptions)),
@ -103,12 +144,14 @@ public sealed interface MethodSignature
}
/**
* Parses a raw method signature string into a {@linkplain MethodSignature}
* Parses a raw method signature string into a {@code MethodSignature}.
*
* @param methodSignature the raw method signature string
* @return method signature
* @return the parsed method signature
* @throws IllegalArgumentException if the string is not a valid method
* signature string
*/
public static MethodSignature parseFrom(String methodSignature) {
return new SignaturesImpl(methodSignature).parseMethodSignature();
}
}