core: Cleanup and documentation

core/src/main/java/com/electronwill/nightconfig/core/conversion/InvalidValueException.java

@@ -1,11 +1,16 @@
 package com.electronwill.nightconfig.core.conversion;
 
 /**
- * Thrown when a value that is associated to a field, or that should become associated to a
- * field, doesn't conform to the @Spec(something) annotation of that field.
+ * Thrown when a value that is associated to a field, or that should become
+ * associated to a field, doesn't conform to the {@code @Spec(something)}
+ * annotation of that field.
  *
+ * @deprecated Use the new package
+ *             {@link com.electronwill.nightconfig.core.serde} with
+ *             {@code serde.annotations}.
  * @author TheElectronWill
  */
+@Deprecated
 public final class InvalidValueException extends RuntimeException {
 	public InvalidValueException(String message) {
 		super(message);
@@ -25,4 +30,4 @@ public InvalidValueException(String message, Throwable cause) {
 	public InvalidValueException(String messageFormat, Object... args) {
 		super(String.format(messageFormat, args));
 	}
-}
+}

core/src/main/java/com/electronwill/nightconfig/core/conversion/ReflectionException.java

@@ -3,8 +3,12 @@
 /**
  * Thrown when an important reflective operation fails.
  *
+ * @deprecated Use the new package
+ *             {@link com.electronwill.nightconfig.core.serde} with
+ *             {@code serde.annotations}.
  * @author TheElectronWill
  */
+@Deprecated
 public class ReflectionException extends RuntimeException {
 	public ReflectionException(String message) {
 		super(message);
@@ -13,4 +17,4 @@ public ReflectionException(String message) {
 	public ReflectionException(String message, Throwable cause) {
 		super(message, cause);
 	}
-}
+}

core/src/main/java/com/electronwill/nightconfig/core/conversion/package-info.java

@@ -1,9 +1,9 @@
 /**
- * Provides tools for converting configurations to/from Java objects, and converting config values on the fly.
+ * <b>(deprecated)</b> Provides tools for converting configurations to/from Java objects, and converting config values on the fly.
  * <p>
  * The most useful class in this package is {@link com.electronwill.nightconfig.core.conversion.ObjectConverter},
  * which performs object-to-config deserialization and config-to-object serialization.
- * 
- * @see ObjectConverter
+ * <p>
+ * <b>Note: as of NightConfig 3.7.0, this package is replaced by {@link com.electronwill.nightconfig.core.serde}.</b>
  */
 package com.electronwill.nightconfig.core.conversion;

core/src/main/java/com/electronwill/nightconfig/core/serde/DeserializerContext.java

@@ -12,6 +12,9 @@
 import com.electronwill.nightconfig.core.UnmodifiableConfig;
 import com.electronwill.nightconfig.core.serde.annotations.*;
 
+/**
+ * Holds deserialization settings and provides some base deserialization logic.
+ */
 public final class DeserializerContext {
 	final AbstractObjectDeserializer settings;
 

core/src/main/java/com/electronwill/nightconfig/core/serde/ObjectDeserializerBuilder.java

@@ -10,7 +10,7 @@
 import com.electronwill.nightconfig.core.UnmodifiableConfig;
 
 /**
- * Implements Config to Object deserialization.
+ * Builder for {@link ObjectDeserializer}.
  */
 public final class ObjectDeserializerBuilder {
 

core/src/main/java/com/electronwill/nightconfig/core/serde/ObjectSerializer.java

@@ -7,6 +7,7 @@
 import java.util.function.Supplier;
 
 import com.electronwill.nightconfig.core.Config;
+import com.electronwill.nightconfig.core.UnmodifiableConfig;
 import com.electronwill.nightconfig.core.ConfigFormat;
 import com.electronwill.nightconfig.core.file.FileConfig;
 import com.electronwill.nightconfig.core.serde.annotations.SerdeDefault;

core/src/main/java/com/electronwill/nightconfig/core/serde/ObjectSerializerBuilder.java

@@ -11,7 +11,7 @@
 import com.electronwill.nightconfig.core.UnmodifiableConfig;
 
 /**
- * Implements Object to Config serialization.
+ * Builder for {@link ObjectSerializer}.
  */
 public final class ObjectSerializerBuilder {
     final IdentityHashMap<Class<?>, ValueSerializer<?, ?>> classBasedSerializers = new IdentityHashMap<>(7);

core/src/main/java/com/electronwill/nightconfig/core/serde/SerdeAssertException.java

@@ -1,5 +1,10 @@
 package com.electronwill.nightconfig.core.serde;
 
+/**
+ * Thrown when an assertion, specified on a field by an annotation of type
+ * {@link com.electronwill.nightconfig.core.serde.annotations.SerdeAssert},
+ * is not verified during (de)serialization.
+ */
 public final class SerdeAssertException extends SerdeException {
     SerdeAssertException(String message) {
         super(message);

core/src/main/java/com/electronwill/nightconfig/core/serde/SerdeException.java

@@ -1,5 +1,9 @@
 package com.electronwill.nightconfig.core.serde;
 
+/**
+ * Thrown when an error occurs during the serialization
+ * or deserialization process.
+ */
 public class SerdeException extends RuntimeException {
     SerdeException(String message) {
         super(message);

core/src/main/java/com/electronwill/nightconfig/core/serde/SerializerContext.java

@@ -12,6 +12,9 @@
 import com.electronwill.nightconfig.core.ConfigFormat;
 import com.electronwill.nightconfig.core.serde.annotations.*;
 
+/**
+ * Holds serialization settings and provides some base serialization logic.
+ */
 public final class SerializerContext {
 	final ObjectSerializer settings;
 	final Supplier<? extends ConfigFormat<?>> formatSupplier;

core/src/main/java/com/electronwill/nightconfig/core/serde/annotations/SerdeAssert.java

@@ -1,8 +1,6 @@
 package com.electronwill.nightconfig.core.serde.annotations;
 
-import java.lang.annotation.Repeatable;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.*;
 
 /**
  * Throw an exception if the annotated field does not match the given condition.
@@ -33,6 +31,7 @@
  */
 @Repeatable(SerdeAssertsContainer.class)
 @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
 public @interface SerdeAssert {
 	/**
 	 * One or multiple assertions to check.
@@ -94,6 +93,11 @@ String customCheck()
 	 */
 	SerdePhase phase() default SerdePhase.BOTH;
 
+	/**
+	 * An condition that the field's value must verify during (de)serialization.
+	 * <p>
+	 * An exception is thrown if the field does not satisfy the condition.
+	 */
 	public static enum AssertThat {
 		/**
 		 * Throw an exception if the field is null.

core/src/main/java/com/electronwill/nightconfig/core/serde/annotations/SerdeAssertsContainer.java

@@ -1,7 +1,6 @@
 package com.electronwill.nightconfig.core.serde.annotations;
 
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.*;
 
 /**
  * A container for multiple {@link SerdeAssert} annotations, because
@@ -11,6 +10,7 @@
  * you should simply repeat the {@code @SerdeAssert} annotation multiple times.
  */
 @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
 public @interface SerdeAssertsContainer {
 	SerdeAssert[] value();
 }

core/src/main/java/com/electronwill/nightconfig/core/serde/annotations/SerdeComment.java

@@ -1,8 +1,6 @@
 package com.electronwill.nightconfig.core.serde.annotations;
 
-import java.lang.annotation.Repeatable;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.*;
 
 import com.electronwill.nightconfig.core.CommentedConfig;
 import com.electronwill.nightconfig.core.io.ConfigWriter;
@@ -34,6 +32,7 @@
  */
 @Repeatable(SerdeCommentsContainer.class)
 @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
 public @interface SerdeComment {
 	String value();
 }

core/src/main/java/com/electronwill/nightconfig/core/serde/annotations/SerdeCommentsContainer.java

@@ -1,8 +1,6 @@
 package com.electronwill.nightconfig.core.serde.annotations;
 
-import java.lang.annotation.Repeatable;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.*;
 
 /**
  * A container for multiple {@link SerdeComment} annotations, because
@@ -12,6 +10,7 @@
  * you should simply repeat the {@code @SerdeComment} annotation multiple times.
  */
 @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
 public @interface SerdeCommentsContainer {
 	SerdeComment[] value();
 }

core/src/main/java/com/electronwill/nightconfig/core/serde/annotations/SerdeDefault.java

@@ -1,8 +1,6 @@
 package com.electronwill.nightconfig.core.serde.annotations;
 
-import java.lang.annotation.Repeatable;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.*;
 
 import com.electronwill.nightconfig.core.Config;
 
@@ -84,6 +82,7 @@
  */
 @Repeatable(SerdeDefaultsContainer.class)
 @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
 public @interface SerdeDefault {
 	/**
 	 * The class that defines the method that provides the default value.
@@ -136,6 +135,11 @@
 	 */
 	WhenValue[] whenValue() default { WhenValue.IS_MISSING };
 
+	/**
+	 * A condition that defines when to use the default value during (de)serialization.
+	 * <p>
+	 * The default value is used if the condition is true.
+	 */
 	public static enum WhenValue {
 		/**
 		 * When deserializing a field, call the default value provider if the value is

core/src/main/java/com/electronwill/nightconfig/core/serde/annotations/SerdeDefaultsContainer.java

@@ -1,8 +1,6 @@
 package com.electronwill.nightconfig.core.serde.annotations;
 
-import java.lang.annotation.Repeatable;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.*;
 
 /**
  * A container for multiple {@link SerdeDefault} annotations, because
@@ -12,6 +10,7 @@
  * you should simply repeat the {@code @SerdeDefault} annotation multiple times.
  */
 @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
 public @interface SerdeDefaultsContainer {
 	SerdeDefault[] value();
 }

core/src/main/java/com/electronwill/nightconfig/core/serde/annotations/SerdeKey.java

@@ -1,7 +1,6 @@
 package com.electronwill.nightconfig.core.serde.annotations;
 
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.*;
 
 /**
  * Sets the key to use when serializing/deserializing an element, instead of its
@@ -32,6 +31,7 @@
  * </pre>
  */
 @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
 public @interface SerdeKey {
 	String value();
 }

core/src/main/java/com/electronwill/nightconfig/core/serde/annotations/SerdeSkipDeserializingIf.java

@@ -1,7 +1,6 @@
 package com.electronwill.nightconfig.core.serde.annotations;
 
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.*;
 
 import com.electronwill.nightconfig.core.UnmodifiableConfig;
 
@@ -78,6 +77,7 @@
  * </code></pre>
  */
 @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
 public @interface SerdeSkipDeserializingIf {
 	/**
 	 * The type of skip predicate: either a predefined condition, or {@code CUSTOM}.
@@ -120,6 +120,11 @@
 	 */
 	String customCheck() default "";
 
+	/**
+	 * A condition that defines when to skip the field during deserialization.
+	 * <p>
+	 * The field is skipped if the condition is true.
+	 */
 	public static enum SkipDeIf {
 		/**
 		 * Skip the field if the corresponding config entry is missing.

core/src/main/java/com/electronwill/nightconfig/core/serde/annotations/SerdeSkipSerializingIf.java

@@ -1,7 +1,6 @@
 package com.electronwill.nightconfig.core.serde.annotations;
 
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.*;
 
 /**
  * Don't serialize the annotated field if some condition is true.
@@ -61,6 +60,7 @@
  * </code></pre>
  */
 @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
 public @interface SerdeSkipSerializingIf {
 	/**
 	 * The type of skip predicate: either a predefined condition, or {@code CUSTOM}.
@@ -105,6 +105,11 @@
 	 */
 	String customCheck() default "";
 
+	/**
+	 * A condition that defines when to skip the field during serialization.
+	 * <p>
+	 * The field is skipped if the condition is true.
+	 */
 	public static enum SkipSerIf {
 		/**
 		 * Skip the field if it's null.