(struts) 10/14: WW-3871 docs(core): document conversion key derivation and field level support

[lu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

lukaszlenart pushed a commit to branch WW-3871-typeconversion-key-derivation
in repository https://gitbox.apache.org/repos/asf/struts.git

commit 0c86a3a1e0b28e413a389853cd1c053baf8c19de
Author: Lukasz Lenart <lu...@apache.org>
AuthorDate: Sat Jul 25 15:45:29 2026 +0200

    WW-3871 docs(core): document conversion key derivation and field level support
---
 .../conversion/annotations/TypeConversion.java      | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/core/src/main/java/org/apache/struts2/conversion/annotations/TypeConversion.java b/core/src/main/java/org/apache/struts2/conversion/annotations/TypeConversion.java
index 749d715c9..c65b5d08e 100644
--- a/core/src/main/java/org/apache/struts2/conversion/annotations/TypeConversion.java
+++ b/core/src/main/java/org/apache/struts2/conversion/annotations/TypeConversion.java
@@ -48,7 +48,7 @@ import java.lang.annotation.Target;
  * <p><u>Annotation usage:</u></p>
  *
  * <!-- START SNIPPET: usage -->
- * <p>The TypeConversion annotation can be applied at property and method level.</p>
+ * <p>The TypeConversion annotation can be applied at field and method level.</p>
  * <!-- END SNIPPET: usage -->
  *
  * <p><u>Annotation parameters:</u></p>
@@ -67,8 +67,11 @@ import java.lang.annotation.Target;
  * <tr>
  * <td>key</td>
  * <td>no</td>
- * <td>The annotated property/key name</td>
- * <td>The optional property name mostly used within TYPE level annotations.</td>
+ * <td>The annotated property/field name</td>
+ * <td>The property name the rule applies to. The matching prefix for the given rule
+ * (<code>Key_</code>, <code>Element_</code>, <code>KeyProperty_</code>, <code>CreateIfNull_</code>)
+ * is prepended automatically unless the key already carries it. Required on TYPE level annotations,
+ * where there is no member name to derive it from.</td>
  * </tr>
  * <tr>
  * <td>type</td>
@@ -129,6 +132,9 @@ import java.lang.annotation.Target;
  *       this.convertDouble = convertDouble;
  *   }
  *
+ *   &#64;TypeConversion(rule = ConversionRule.CREATE_IF_NULL, value = "true")
+ *   private List users = null;
+ *
  *   &#64;TypeConversion(rule = ConversionRule.COLLECTION, converterClass = String.class)
  *   public void setUsers( List users ) {
  *       this.users = users;
@@ -155,10 +161,15 @@ import java.lang.annotation.Target;
 public @interface TypeConversion {
 
     /**
-     * The optional key name used within TYPE level annotations.
-     * Defaults to the property name.
+     * The property name this conversion applies to. Optional on fields and methods, where it
+     * defaults to the property name; required on TYPE level annotations.
+     *
+     * <p>The prefix matching the declared {@link ConversionRule} is prepended automatically, so
+     * {@code @TypeConversion(key = "users", rule = ConversionRule.CREATE_IF_NULL, value = "true")}
+     * and {@code @TypeConversion(key = "CreateIfNull_users", ...)} are equivalent.</p>
      *
      * @return key
+     * @since 7.3.0 the rule prefix is derived; previously the full key had to be spelled out
      */
     String key() default "";