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

42
src/java.base/share/classes/java/lang/classfile/Attribute.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
@ -31,15 +31,31 @@ import jdk.internal.classfile.impl.BoundAttribute;
import jdk.internal.classfile.impl.UnboundAttribute;
/**
* Models a classfile attribute (JVMS {@jvms 4.7}). Many, though not all, subtypes of
* {@linkplain Attribute} will implement {@link ClassElement}, {@link
* MethodElement}, {@link FieldElement}, or {@link CodeElement}; attributes that
* are also elements will be delivered when traversing the elements of the
* corresponding model type. Additionally, all attributes are accessible
* directly from the corresponding model type through {@link
* AttributedElement#findAttribute(AttributeMapper)}.
* @param <A> the attribute type
* Models an attribute (JVMS {@jvms 4.7}) in the {@code class} file format.
* Attributes exist on certain {@code class} file structures modeled by {@link
* AttributedElement}, which provides basic read access to the attributes.
* <p>
* This sealed interface hierarchy includes attributes predefined in the JVMS
* and JDK-specific nonstandard attributes. Their {@linkplain #attributeMapper()
* mappers} are available in {@link Attributes}. Two special subtypes of {@code
* Attribute} are {@link CustomAttribute}, which all user-defined attributes
* should extend from, and {@link UnknownAttribute}, representing attributes
* read from {@code class} file but are not recognized by the {@link
* ClassFile.AttributeMapperOption}.
* <p>
* Attributes are read through {@link AttributedElement} or element traversal of
* a {@link CompoundElement}; they are written through {@link ClassFileBuilder}.
* See {@linkplain java.lang.classfile.attribute##reading Reading Attributes}
* and {@linkplain java.lang.classfile.attribute##writing Writing Attributes}
* for more details.
*
* @param <A> the attribute type
* @see java.lang.classfile.attribute
* @see AttributeMapper
* @see AttributedElement
* @see CustomAttribute
* @see UnknownAttribute
* @jvms 4.7 Attributes
* @sealedGraph
* @since 24
*/
@ -62,7 +78,13 @@ public sealed interface Attribute<A extends Attribute<A>>
StackMapTableAttribute, SyntheticAttribute,
UnknownAttribute, BoundAttribute, UnboundAttribute, CustomAttribute {
/**
* {@return the name of the attribute}
* {@return the name of the attribute} The {@linkplain
* Utf8Entry#stringValue() string value} of the name is equivalent to the
* value of {@link AttributeMapper#name() attributeMapper().name()}.
* <p>
* If this attribute is read from a {@code class} file, this method returns
* the {@link Utf8Entry} indicating the attribute name in the {@code class}
* file.
*/
Utf8Entry attributeName();