documentation for Array methods and improve parameter descriptions

Author: brokkoli71

src/main/java/dev/zarr/zarrjava/interfaces/Array.java

@@ -22,9 +22,9 @@ public interface Array {
      * Writes a ucar.ma2.Array into the Zarr array at a specified offset. The shape of the Zarr array
      * needs be large enough for the write.
      *
-     * @param offset
-     * @param array
-     * @param parallel
+     * @param offset the offset where to write the data
+     * @param array the data to write
+     * @param parallel utilizes parallelism if true
      */
     default void write(long[] offset, ucar.ma2.Array array, boolean parallel) {
         ArrayMetadata metadata = metadata();
@@ -74,11 +74,12 @@ default void write(long[] offset, ucar.ma2.Array array, boolean parallel) {
 
     /**
      * Writes one chunk into the Zarr array as specified by the chunk coordinates. The shape of the
-     * Zarr array needs be large enough for the write.
+     * Zarr array needs to be large enough to write.
      *
-     * @param chunkCoords
-     * @param chunkArray
-     * @throws ZarrException
+     * @param chunkCoords The coordinates of the chunk as computed by the offset of the chunk divided
+     *                    by the chunk shape.
+     * @param chunkArray The data to write into the chunk
+     * @throws ZarrException throws ZarrException if the write fails
      */
     default void writeChunk(long[] chunkCoords, ucar.ma2.Array chunkArray) throws ZarrException {
         ArrayMetadata metadata = metadata();
@@ -99,7 +100,7 @@ default void writeChunk(long[] chunkCoords, ucar.ma2.Array chunkArray) throws Za
      *
      * @param chunkCoords The coordinates of the chunk as computed by the offset of the chunk divided
      *                    by the chunk shape.
-     * @throws ZarrException
+     * @throws ZarrException throws ZarrException if the requested chunk is outside the array's domain or if the read fails
      */
     @Nonnull
     default ucar.ma2.Array readChunk(long[] chunkCoords)
@@ -126,7 +127,7 @@ default ucar.ma2.Array readChunk(long[] chunkCoords)
      * the Zarr array needs be large enough for the write.
      * Utilizes no parallelism.
      *
-     * @param array
+     * @param array the data to write
      */
     default void write(ucar.ma2.Array array) {
         write(new long[metadata().ndim()], array);
@@ -137,8 +138,8 @@ default void write(ucar.ma2.Array array) {
      * needs be large enough for the write.
      * Utilizes no parallelism.
      *
-     * @param offset
-     * @param array
+     * @param offset the offset where to write the data
+     * @param array the data to write
      */
     default void write(long[] offset, ucar.ma2.Array array) {
         write(offset, array, false);
@@ -148,8 +149,8 @@ default void write(long[] offset, ucar.ma2.Array array) {
      * Writes a ucar.ma2.Array into the Zarr array at the beginning of the Zarr array. The shape of
      * the Zarr array needs be large enough for the write.
      *
-     * @param array
-     * @param parallel
+     * @param array the data to write
+     * @param parallel utilizes parallelism if true
      */
     default void write(ucar.ma2.Array array, boolean parallel) {
         write(new long[metadata().ndim()], array, parallel);
@@ -159,7 +160,7 @@ default void write(ucar.ma2.Array array, boolean parallel) {
      * Reads the entire Zarr array into an ucar.ma2.Array.
      * Utilizes no parallelism.
      *
-     * @throws ZarrException
+     * @throws ZarrException throws ZarrException if the read fails
      */
     @Nonnull
     default ucar.ma2.Array read() throws ZarrException {
@@ -170,9 +171,9 @@ default ucar.ma2.Array read() throws ZarrException {
      * Reads a part of the Zarr array based on a requested offset and shape into an ucar.ma2.Array.
      * Utilizes no parallelism.
      *
-     * @param offset
-     * @param shape
-     * @throws ZarrException
+     * @param offset the offset where to start reading
+     * @param shape the shape of the data to read
+     * @throws ZarrException throws ZarrException if the requested data is outside the array's domain or if the read fails
      */
     @Nonnull
     default ucar.ma2.Array read(final long[] offset, final int[] shape) throws ZarrException {
@@ -182,8 +183,8 @@ default ucar.ma2.Array read(final long[] offset, final int[] shape) throws ZarrE
     /**
      * Reads the entire Zarr array into an ucar.ma2.Array.
      *
-     * @param parallel
-     * @throws ZarrException
+     * @param parallel utilizes parallelism if true
+     * @throws ZarrException throws ZarrException if the requested data is outside the array's domain or if the read fails
      */
     @Nonnull
     default ucar.ma2.Array read(final boolean parallel) throws ZarrException {
@@ -209,10 +210,10 @@ default boolean chunkIsInArray(long[] chunkCoords) {
     /**
      * Reads a part of the Zarr array based on a requested offset and shape into an ucar.ma2.Array.
      *
-     * @param offset
-     * @param shape
-     * @param parallel
-     * @throws ZarrException
+     * @param offset the offset where to start reading
+     * @param shape the shape of the data to read
+     * @param parallel utilizes parallelism if true
+     * @throws ZarrException throws ZarrException if the requested data is outside the array's domain or if the read fails
      */
     @Nonnull
     default ucar.ma2.Array read(final long[] offset, final int[] shape, final boolean parallel) throws ZarrException {

src/main/java/dev/zarr/zarrjava/v2/Array.java

@@ -3,21 +3,17 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.zarr.zarrjava.ZarrException;
 import dev.zarr.zarrjava.store.StoreHandle;
-import dev.zarr.zarrjava.utils.IndexingUtils;
-import dev.zarr.zarrjava.utils.MultiArrayUtils;
 import dev.zarr.zarrjava.utils.Utils;
 import dev.zarr.zarrjava.v3.codec.CodecPipeline;
 import dev.zarr.zarrjava.v3.codec.Codec;
 import dev.zarr.zarrjava.v3.codec.core.BytesCodec;
-import ucar.ma2.InvalidRangeException;
 
 import javax.annotation.Nonnull;
 import java.io.IOException;
 import java.nio.ByteBuffer;
 import java.util.Arrays;
 import java.util.function.Function;
 import java.util.stream.Collectors;
-import java.util.stream.Stream;
 
 import static dev.zarr.zarrjava.v3.Node.makeObjectMapper;
 
@@ -38,6 +34,13 @@ protected Array(StoreHandle storeHandle, ArrayMetadata arrayMetadata) throws IOE
     ), metadata.coreArrayMetadata);
   }
 
+  /**
+   * Opens an existing Zarr array at a specified storage location.
+   *
+   * @param storeHandle the storage location of the Zarr array
+   * @throws IOException throws IOException if the metadata cannot be read
+   * @throws ZarrException throws ZarrException if the Zarr array cannot be opened
+   */
   public static Array open(StoreHandle storeHandle) throws IOException, ZarrException {
     return new Array(
         storeHandle,
@@ -49,11 +52,32 @@ public static Array open(StoreHandle storeHandle) throws IOException, ZarrExcept
     );
   }
 
+  /**
+   * Creates a new Zarr array with the provided metadata at a specified storage location. This
+   * method will raise an exception if a Zarr array already exists at the specified storage
+   * location.
+   *
+   * @param storeHandle the storage location of the Zarr array
+   * @param arrayMetadata the metadata of the Zarr array
+   * @throws IOException if the metadata cannot be serialized
+   * @throws ZarrException if the Zarr array cannot be created
+   */
   public static Array create(StoreHandle storeHandle, ArrayMetadata arrayMetadata)
       throws IOException, ZarrException {
     return Array.create(storeHandle, arrayMetadata, false);
   }
 
+  /**
+   * Creates a new Zarr array with the provided metadata at a specified storage location. If
+   * `existsOk` is false, this method will raise an exception if a Zarr array already exists at the
+   * specified storage location.
+   *
+   * @param storeHandle the storage location of the Zarr array
+   * @param arrayMetadata the metadata of the Zarr array
+   * @param existsOk if true, no exception is raised if the Zarr array already exists
+   * @throws IOException throws IOException if the metadata cannot be serialized
+   * @throws ZarrException throws ZarrException if the Zarr array cannot be created
+   */
   public static Array create(StoreHandle storeHandle, ArrayMetadata arrayMetadata, boolean existsOk)
       throws IOException, ZarrException {
     StoreHandle metadataHandle = storeHandle.resolve(ZARRAY);
@@ -85,8 +109,6 @@ public static ArrayMetadataBuilder metadataBuilder(ArrayMetadata existingMetadat
     return ArrayMetadataBuilder.fromArrayMetadata(existingMetadata);
   }
 
-
-
   @Override
   public String toString() {
     return String.format("<v2.Array {%s} (%s) %s>", storeHandle,

src/main/java/dev/zarr/zarrjava/v3/Array.java

@@ -3,7 +3,6 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import dev.zarr.zarrjava.ZarrException;
 import dev.zarr.zarrjava.store.StoreHandle;
-import dev.zarr.zarrjava.utils.MultiArrayUtils;
 import dev.zarr.zarrjava.utils.Utils;
 import dev.zarr.zarrjava.v3.codec.CodecPipeline;
 import java.io.IOException;
@@ -21,7 +20,7 @@ public class Array extends Node implements dev.zarr.zarrjava.interfaces.Array {
   CodecPipeline codecPipeline;
 
   protected Array(StoreHandle storeHandle, ArrayMetadata arrayMetadata)
-      throws IOException, ZarrException {
+      throws ZarrException {
     super(storeHandle);
     this.metadata = arrayMetadata;
     this.codecPipeline = new CodecPipeline(arrayMetadata.codecs, arrayMetadata.coreArrayMetadata);
@@ -30,9 +29,9 @@ protected Array(StoreHandle storeHandle, ArrayMetadata arrayMetadata)
   /**
    * Opens an existing Zarr array at a specified storage location.
    *
-   * @param storeHandle
-   * @throws IOException
-   * @throws ZarrException
+   * @param storeHandle the storage location of the Zarr array
+   * @throws IOException throws IOException if the metadata cannot be read
+   * @throws ZarrException throws ZarrException if the Zarr array cannot be opened
    */
   public static Array open(StoreHandle storeHandle) throws IOException, ZarrException {
     return new Array(
@@ -50,10 +49,10 @@ public static Array open(StoreHandle storeHandle) throws IOException, ZarrExcept
    * method will raise an exception if a Zarr array already exists at the specified storage
    * location.
    *
-   * @param storeHandle
-   * @param arrayMetadata
-   * @throws IOException
-   * @throws ZarrException
+   * @param storeHandle the storage location of the Zarr array
+   * @param arrayMetadata the metadata of the Zarr array
+   * @throws IOException if the metadata cannot be serialized
+   * @throws ZarrException if the Zarr array cannot be created
    */
   public static Array create(StoreHandle storeHandle, ArrayMetadata arrayMetadata)
       throws IOException, ZarrException {
@@ -65,11 +64,11 @@ public static Array create(StoreHandle storeHandle, ArrayMetadata arrayMetadata)
    * `existsOk` is false, this method will raise an exception if a Zarr array already exists at the
    * specified storage location.
    *
-   * @param storeHandle
-   * @param arrayMetadata
-   * @param existsOk
-   * @throws IOException
-   * @throws ZarrException
+   * @param storeHandle the storage location of the Zarr array
+   * @param arrayMetadata the metadata of the Zarr array
+   * @param existsOk if true, no exception is raised if the Zarr array already exists
+   * @throws IOException throws IOException if the metadata cannot be serialized
+   * @throws ZarrException throws ZarrException if the Zarr array cannot be created
    */
   public static Array create(StoreHandle storeHandle, ArrayMetadata arrayMetadata, boolean existsOk)
       throws IOException, ZarrException {
@@ -91,11 +90,12 @@ public static Array create(StoreHandle storeHandle, ArrayMetadata arrayMetadata,
    * be used to construct the metadata of the Zarr array. If `existsOk` is false, this method will
    * raise an exception if a Zarr array already exists at the specified storage location.
    *
-   * @param storeHandle
-   * @param arrayMetadataBuilderMapper
-   * @param existsOk
-   * @throws IOException
-   * @throws ZarrException
+   * @param storeHandle the storage location of the Zarr array
+   * @param arrayMetadataBuilderMapper a callback of ArrayMetadataBuilder -> ArrayMetadataBuilder that is
+   *                                   used to construct the metadata of the Zarr array
+   * @param existsOk if true, no exception is raised if the Zarr array already exists
+   * @throws IOException if the metadata cannot be serialized
+   * @throws ZarrException if the Zarr array cannot be created
    */
   public static Array create(StoreHandle storeHandle,
       Function<ArrayMetadataBuilder, ArrayMetadataBuilder> arrayMetadataBuilderMapper,
@@ -142,9 +142,9 @@ private Array writeMetadata(ArrayMetadata newArrayMetadata) throws ZarrException
    * deleted. This method returns a new instance of the Zarr array class and the old instance
    * becomes invalid.
    *
-   * @param newShape
-   * @throws ZarrException
-   * @throws IOException
+   * @param newShape the new shape of the Zarr array
+   * @throws ZarrException if the new metadata is invalid
+   * @throws IOException throws IOException if the new metadata cannot be serialized
    */
   public Array resize(long[] newShape) throws ZarrException, IOException {
     if (newShape.length != metadata.ndim()) {
@@ -162,9 +162,9 @@ public Array resize(long[] newShape) throws ZarrException, IOException {
    * Sets the attributes of the Zarr array. It overwrites and removes any existing attributes. This
    * method returns a new instance of the Zarr array class and the old instance becomes invalid.
    *
-   * @param newAttributes
-   * @throws ZarrException
-   * @throws IOException
+   * @param newAttributes the new attributes of the Zarr array
+   * @throws ZarrException throws ZarrException if the new metadata is invalid
+   * @throws IOException throws IOException if the new metadata cannot be serialized
    */
   public Array setAttributes(Map<String, Object> newAttributes) throws ZarrException, IOException {
     ArrayMetadata newArrayMetadata =
@@ -180,9 +180,10 @@ public Array setAttributes(Map<String, Object> newAttributes) throws ZarrExcepti
    * callback may be mutated. This method overwrites and removes any existing attributes. This
    * method returns a new instance of the Zarr array class and the old instance becomes invalid.
    *
-   * @param attributeMapper
-   * @throws ZarrException
-   * @throws IOException
+   * @param attributeMapper a callback of Map<String, Object> -> Map<String, Object> that is used to construct the new
+   *                        attributes
+   * @throws ZarrException throws ZarrException if the new metadata is invalid
+   * @throws IOException throws IOException if the new metadata cannot be serialized
    */
   public Array updateAttributes(Function<Map<String, Object>, Map<String, Object>> attributeMapper)
       throws ZarrException, IOException {

src/test/java/dev/zarr/zarrjava/ZarrTest.java

@@ -12,7 +12,6 @@
 import dev.zarr.zarrjava.v3.*;
 import dev.zarr.zarrjava.v3.codec.Codec;
 import dev.zarr.zarrjava.v3.codec.CodecBuilder;
-import dev.zarr.zarrjava.v3.codec.core.BloscCodec;
 import dev.zarr.zarrjava.v3.codec.core.BytesCodec;
 import dev.zarr.zarrjava.v3.codec.core.ShardingIndexedCodec;
 import dev.zarr.zarrjava.v3.codec.core.TransposeCodec;