docs(core): enhance documentation and add core interfaces

cosid-core/src/main/java/me/ahoo/cosid/accessor/AbstractIdMetadata.java

@@ -18,7 +18,10 @@
 
 
 /**
- * Abstract {@link IdMetadata}.
+ * Abstract base implementation of {@link IdMetadata}.
+ *
+ * <p>Provides common functionality for ID metadata implementations,
+ * including lazy generator initialization.
  *
  * @author ahoo wang
  */
@@ -27,6 +30,11 @@ public abstract class AbstractIdMetadata implements IdMetadata {
     private final IdDefinition idDefinition;
     private final LazyIdGenerator idGenerator;
 
+    /**
+     * Creates an instance with the given ID definition.
+     *
+     * @param idDefinition the ID definition
+     */
     public AbstractIdMetadata(IdDefinition idDefinition) {
         this.idDefinition = idDefinition;
         this.idGenerator = new LazyIdGenerator(idDefinition.getGeneratorName());

cosid-core/src/main/java/me/ahoo/cosid/accessor/CosIdGetter.java

@@ -14,12 +14,20 @@
 package me.ahoo.cosid.accessor;
 
 /**
- * CosId Getter.
+ * Interface for getting the ID value from an object.
+ *
+ * <p>Used by frameworks (MyBatis, etc.) to extract the ID from entities.
  *
  * @author ahoo wang
  */
 public interface CosIdGetter {
 
+    /**
+     * Gets the ID value from the target object.
+     *
+     * @param target the object to get ID from
+     * @return the ID value
+     */
     Object getId(Object target);
 
 }

cosid-core/src/main/java/me/ahoo/cosid/accessor/CosIdSetter.java

@@ -14,12 +14,20 @@
 package me.ahoo.cosid.accessor;
 
 /**
- * CosId Setter.
+ * Interface for setting the ID value on an object.
+ *
+ * <p>Used by frameworks (MyBatis, etc.) to set the ID on entities.
  *
  * @author ahoo wang
  */
 public interface CosIdSetter {
 
+    /**
+     * Sets the ID value on the target object.
+     *
+     * @param target the object to set ID on
+     * @param id     the ID value to set
+     */
     void setId(Object target, Object id);
 
 }

cosid-core/src/main/java/me/ahoo/cosid/accessor/DefaultCosIdAccessor.java

@@ -21,6 +21,9 @@
 /**
  * Default {@link CosIdAccessor} implementation.
  *
+ * <p>Provides ID get/set operations on entities and ensures IDs are generated
+ * when missing. Supports Long, Integer, and String ID types.
+ *
  * @author ahoo wang
  */
 public class DefaultCosIdAccessor extends AbstractIdMetadata implements CosIdAccessor {
@@ -29,6 +32,13 @@ public class DefaultCosIdAccessor extends AbstractIdMetadata implements CosIdAcc
     private final CosIdSetter setter;
     private final EnsureId ensureId;
 
+    /**
+     * Creates a new accessor.
+     *
+     * @param idDefinition the ID definition
+     * @param getter      the getter for extracting ID from entities
+     * @param setter      the setter for setting ID on entities
+     */
     public DefaultCosIdAccessor(IdDefinition idDefinition, CosIdGetter getter, CosIdSetter setter) {
         super(idDefinition);
         this.getter = getter;
@@ -57,10 +67,20 @@ public void setId(Object target, Object id) {
         setter.setId(target, id);
     }
 
+    /**
+     * Gets the getter.
+     *
+     * @return the getter
+     */
     public CosIdGetter getGetter() {
         return getter;
     }
 
+    /**
+     * Gets the setter.
+     *
+     * @return the setter
+     */
     public CosIdSetter getSetter() {
         return setter;
     }
@@ -71,6 +91,9 @@ public boolean ensureId(Object target) {
         return ensureId.ensureId(target);
     }
 
+    /**
+     * Ensures ID is generated for String ID types.
+     */
     public class EnsureStringId implements EnsureId {
 
         @Override
@@ -85,6 +108,9 @@ public boolean ensureId(Object target) {
         }
     }
 
+    /**
+     * Ensures ID is generated for Long ID types.
+     */
     public class EnsureLongId implements EnsureId {
         private static final long MIN_ID = 0;
 
@@ -99,6 +125,9 @@ public boolean ensureId(Object target) {
         }
     }
 
+    /**
+     * Ensures ID is generated for Integer ID types.
+     */
     public class EnsureIntegerId implements EnsureId {
         private static final int MIN_ID = 0;
         private final IntegerIdGenerator integerIdGenerator;

cosid-core/src/main/java/me/ahoo/cosid/accessor/IdMetadata.java

@@ -20,29 +20,62 @@
 import java.lang.reflect.Field;
 
 /**
- * Id Metadata.
+ * Metadata container for ID field information.
+ *
+ * <p>Provides access to ID definition, generator, and field metadata
+ * for objects annotated with {@code @CosId}.
  *
  * @author ahoo wang
  */
 @Immutable
 public interface IdMetadata {
 
+    /**
+     * Gets the ID definition.
+     *
+     * @return the ID definition
+     */
     IdDefinition getIdDefinition();
 
+    /**
+     * Gets the generator name from the ID definition.
+     *
+     * @return the generator name
+     */
     default String getGeneratorName() {
         return getIdDefinition().getGeneratorName();
     }
 
+    /**
+     * Gets the ID generator.
+     *
+     * @return the ID generator
+     */
     IdGenerator getIdGenerator();
 
+    /**
+     * Gets the ID field from the definition.
+     *
+     * @return the ID field
+     */
     default Field getIdField() {
         return getIdDefinition().getIdField();
     }
 
+    /**
+     * Gets the declaring class of the ID field.
+     *
+     * @return the declaring class
+     */
     default Class<?> getIdDeclaringClass() {
         return getIdField().getDeclaringClass();
     }
 
+    /**
+     * Gets the type of the ID field.
+     *
+     * @return the ID type
+     */
     default Class<?> getIdType() {
         return getIdDefinition().getIdType();
     }

cosid-core/src/main/java/me/ahoo/cosid/accessor/IdTypeNotSupportException.java

@@ -20,19 +20,31 @@
 import java.lang.reflect.Field;
 
 /**
- * ID Type Not Support Exception.
+ * Exception thrown when an ID field type is not supported.
+ *
+ * <p>CosId only supports Long, Integer, and String ID types.
  *
  * @author ahoo wang
  */
 public class IdTypeNotSupportException extends CosIdException {
 
     private final Field idField;
 
+    /**
+     * Creates a new exception.
+     *
+     * @param idField the unsupported ID field
+     */
     public IdTypeNotSupportException(Field idField) {
         super(Strings.lenientFormat("ID type only supports Long/long/Integer/int/String, idField:[%s]!", idField));
         this.idField = idField;
     }
 
+    /**
+     * Gets the unsupported ID field.
+     *
+     * @return the field
+     */
     public Field getIdField() {
         return idField;
     }

cosid-core/src/main/java/me/ahoo/cosid/accessor/MultipleIdNotSupportException.java

@@ -18,19 +18,31 @@
 import com.google.common.base.Strings;
 
 /**
- * Multiple Id Not Support Exception.
+ * Exception thrown when an entity has multiple @CosId fields.
+ *
+ * <p>CosId only supports a single ID field per entity.
  *
  * @author ahoo wang
  */
 public class MultipleIdNotSupportException extends CosIdException {
 
     private final Class<?> declaringClass;
 
+    /**
+     * Creates a new exception.
+     *
+     * @param declaringClass the class with multiple ID fields
+     */
     public MultipleIdNotSupportException(Class<?> declaringClass) {
         super(Strings.lenientFormat("Not support defining multiple CosIds, declaringClass:[%s]!", declaringClass));
         this.declaringClass = declaringClass;
     }
 
+    /**
+     * Gets the declaring class.
+     *
+     * @return the class
+     */
     public Class<?> getDeclaringClass() {
         return declaringClass;
     }

cosid-core/src/main/java/me/ahoo/cosid/accessor/field/FieldGetter.java

@@ -20,13 +20,18 @@
 import java.lang.reflect.Field;
 
 /**
- * Field Getter.
+ * ID getter that accesses field directly.
  *
  * @author ahoo wang
  */
 public class FieldGetter implements CosIdGetter {
     private final Field idField;
 
+    /**
+     * Creates a getter for the specified field.
+     *
+     * @param idField the field to access
+     */
     public FieldGetter(Field idField) {
         CosIdAccessor.ensureAccessible(idField);
         this.idField = idField;

cosid-core/src/main/java/me/ahoo/cosid/accessor/field/FieldSetter.java

@@ -20,13 +20,18 @@
 import java.lang.reflect.Field;
 
 /**
- * Field Setter.
+ * ID setter that accesses field directly.
  *
  * @author ahoo wang
  */
 public class FieldSetter implements CosIdSetter {
     private final Field idField;
 
+    /**
+     * Creates a setter for the specified field.
+     *
+     * @param idField the field to access
+     */
     public FieldSetter(Field idField) {
         CosIdAccessor.ensureAccessible(idField);
         this.idField = idField;

cosid-core/src/main/java/me/ahoo/cosid/accessor/method/MethodGetter.java

@@ -21,18 +21,28 @@
 import java.lang.reflect.Method;
 
 /**
- * Method Getter.
+ * ID getter that accesses via getter method.
  *
  * @author ahoo wang
  */
 public class MethodGetter implements CosIdGetter {
     private final Method getter;
 
+    /**
+     * Creates a getter for the specified method.
+     *
+     * @param getter the getter method
+     */
     public MethodGetter(Method getter) {
         CosIdAccessor.ensureAccessible(getter);
         this.getter = getter;
     }
 
+    /**
+     * Gets the getter method.
+     *
+     * @return the getter method
+     */
     public Method getGetter() {
         return getter;
     }

cosid-core/src/main/java/me/ahoo/cosid/accessor/method/MethodSetter.java

@@ -21,18 +21,28 @@
 import java.lang.reflect.Method;
 
 /**
- * Method Setter.
+ * ID setter that accesses via setter method.
  *
  * @author ahoo wang
  */
 public class MethodSetter implements CosIdSetter {
     private final Method setter;
 
+    /**
+     * Creates a setter for the specified method.
+     *
+     * @param setter the setter method
+     */
     public MethodSetter(Method setter) {
         CosIdAccessor.ensureAccessible(setter);
         this.setter = setter;
     }
 
+    /**
+     * Gets the setter method.
+     *
+     * @return the setter method
+     */
     public Method getSetter() {
         return setter;
     }