TargetIdProperty: improve code example, simplify description

greenrobot-team · greenrobot-team · commit b46935f87719 · 2025-10-28T09:08:15.000+01:00
diff --git a/objectbox-java-api/src/main/java/io/objectbox/annotation/TargetIdProperty.java b/objectbox-java-api/src/main/java/io/objectbox/annotation/TargetIdProperty.java
@@ -22,23 +22,25 @@
 import java.lang.annotation.Target;
 
 /**
- * For a ToOne, changes the name of the property to store the target object ID in from the default name:
+ * For a ToOne, changes the name of its associated target ID (or "relation") property.
  * <p>
  * <pre>{@code
  * @Entity
  * public class Order {
- *     @TargetIdProperty("customerRenamedTargetId")
+ *     // Change from default "customerId" to "customerRef"
+ *     @TargetIdProperty("customerRef")
  *     ToOne<Customer> customer;
- *     long customerRenamedTargetId;
+ *     // Optional: expose target ID property (using changed name)
+ *     long customerRef;
  * }
  * }</pre>
  * <p>
- * By default, a target ID property named like the ToOne property with the suffix "Id" is created implicitly (so without
- * defining it in the @Entity class). Using the example above, without the annotation a "virtual" property named
- * {@code long customerId} would be created.
+ * A target ID property is implicitly created (so without defining it in the {@link Entity @Entity} class) for each
+ * ToOne and stores the ID of the referenced target object. By default, it's named like the ToOne field plus the suffix
+ * "Id" (for example {@code customerId}).
  * <p>
- * Exposing the target ID as an actual field (so not necessarily renamed using this annotation) can be useful for other
- * parsers or serializers, like for JSON.
+ * Like in the example above, it's still possible to expose the target ID property as an actual field (useful for other
+ * parsers or serializers, like for JSON). But make sure to use the changed name for the field.
  * <p>
  * See the <a href="https://docs.objectbox.io/relations">relations documentation</a> for details.
  */
