doc: n5 serialization annotations

Author: bogovicj

src/main/java/org/janelia/saalfeldlab/n5/serialization/JsonArrayUtils.java

@@ -5,6 +5,12 @@
 
 public class JsonArrayUtils {
 
+	/**
+	 * Reverses the order of elements in a JSON array in-place.
+	 *
+	 * @param array the JSON array to reverse; must not be null
+	 * @see N5Annotations.ReverseArray
+	 */
 	public static void reverse(final JsonArray array) {
 
 		JsonElement a;

src/main/java/org/janelia/saalfeldlab/n5/serialization/N5Annotations.java

@@ -7,8 +7,34 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Provides specialized annotations for N5 serialization behaviors.
+ * <p>
+ * This interface defines annotations that control specific serialization
+ * transformations needed for N5 compatibility across different storage
+ * formats, for example, when dealing with dimension ordering conventions.
+ * 
+ * @see ReverseArray
+ */
 public interface N5Annotations extends Serializable {
 
+	/**
+	 * Indicates that an array field should be reversed during serialization/deserialization.
+	 * <p>
+	 * This annotation is used to handle dimension ordering differences between storage formats.
+	 * For example, Zarr uses C-order (row-major) dimension ordering [Z, Y, X], while N5 uses
+	 * F-order (column-major) dimension ordering [X, Y, Z].
+	 * <p>
+	 * Example usage:
+	 * <pre>{@code
+	 * @ReverseArray
+	 * @Parameter("chunk_shape")
+	 * private final int[] shape;  // Will be reversed when serializing
+	 * </pre>
+	 * <p>
+	 * This ensures that dimension-related arrays maintain the correct semantic meaning
+	 * across different storage format conventions.
+	 */
 	@Inherited
 	@Retention(RetentionPolicy.RUNTIME)
 	@Target(ElementType.FIELD)

src/main/java/org/janelia/saalfeldlab/n5/serialization/NameConfig.java

@@ -9,15 +9,68 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Configuration interface for N5 serialization naming and parameter annotations.
+ * <p>
+ * This interface provides a standardized way to configure serialization names and parameters
+ * for N5 components such as compression algorithms and codecs. It defines annotations that
+ * control how classes and their fields are serialized and deserialized for the N5 API.
+ * <p>
+ * Classes implementing this interface can use the provided annotations to:
+ * <ul>
+ *   <li>Define a serialization type name with {@link Name @Name}</li>
+ *   <li>Specify a namespace prefix with {@link Prefix @Prefix}</li>
+ *   <li>Mark fields as serialization parameters with {@link Parameter @Parameter}</li>
+ * </ul>
+ * 
+ * @see Name
+ * @see Prefix
+ * @see Parameter
+ */
 public interface NameConfig extends Serializable {
 
+	/**
+	 * Defines a namespace prefix for serialization.
+	 * <p>
+	 * This annotation specifies a prefix that is prepended to the serialization
+	 * type name, creating a namespaced identifier. This is useful for organizing
+	 * related components into logical groups, usually all the components implementing
+	 * a particular interface.
+	 * <p>
+	 * Example usage:
+	 * <pre>{@code
+	 * @Prefix("codec")
+	 * public interface Codec extends NameConfig {
+	 *     // ...
+	 * }
+	 * }</pre>
+	 * 
+	 * @see Name
+	 */
 	@Retention(RetentionPolicy.RUNTIME)
 	@Inherited
 	@Target(ElementType.TYPE)
 	@interface Prefix {
 		String value();
 	}
 
+	/**
+	 * Specifies the serialization type name for a class.
+	 * <p>
+	 * This annotation defines the string identifier used during serialization and
+	 * deserialization to identify the type. The name should be unique within its
+	 * namespace and is typically a short, descriptive identifier.
+	 * <p>
+	 * Example usage:
+	 * <pre>{@code
+	 * @Name("gzip")
+	 * public class GzipCompression implements Compression {
+	 *     // ...
+	 * }
+	 * }</pre>
+	 * 
+	 * @see Prefix
+	 */
 	@Retention(RetentionPolicy.RUNTIME)
 	@Inherited
 	@Target(ElementType.TYPE)
@@ -26,14 +79,57 @@ public interface NameConfig extends Serializable {
 		String value();
 	}
 
+	/**
+	 * Marks a field as a parameter to be serialized.
+	 * <p>
+	 * This annotation identifies fields that should be included during serialization
+	 * and deserialization. It supports both required and optional parameters.
+	 * <p>
+	 * The {@code value} attribute can be used to specify an alternative name for
+	 * the parameter during serialization. If not specified, the field name is used.
+	 * <p>
+	 * Example usage:
+	 * <pre>{@code
+	 * public class GzipCompression implements Compression {
+	 *     @Parameter
+	 *     private final int level;
+	 *     
+	 *     @Parameter(optional = true)
+	 *     private final boolean useZlib;
+	 * }
+	 * }</pre>
+	 * 
+	 * @see Name
+	 */
 	@Retention(RetentionPolicy.RUNTIME)
 	@Inherited
 	@Target(ElementType.FIELD)
 	@interface Parameter {
+		/**
+		 * Alternative name for the parameter during serialization.
+		 * If empty, the field name is used.
+		 * 
+		 * @return the parameter name, or empty string for field name
+		 */
 		String value() default "";
+		
+		/**
+		 * Whether this parameter is optional.
+		 * Optional parameters may be omitted during deserialization.
+		 * 
+		 * @return {@code true} if the parameter is optional, {@code false} otherwise
+		 */
 		boolean optional() default false;
 	}
 
+	/**
+	 * Returns the serialization type name for this instance.
+	 * <p>
+	 * This method retrieves the value from the {@link Name @Name} annotation
+	 * if present on the class.
+	 * 
+	 * @return the type name from the {@code @Name} annotation, or {@code null} if not annotated
+	 */
 	default String getType() {
 
 		final Name type = getClass().getAnnotation(Name.class);