Address code review feedback and add detailed documentation

Co-authored-by: brokkoli71 <44113112+brokkoli71@users.noreply.github.com>

Author: Copilot

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

@@ -288,9 +288,9 @@ private static Separator detectDimensionSeparator(StoreHandle storeHandle, int[]
         }
 
         try {
-            // List all files in the array directory
+            // List all files in the array directory, excluding metadata files (.zarray, .zattrs, .zgroup)
             String[] chunkFiles = storeHandle.list()
-                .filter(key -> !key.startsWith(".z"))  // Exclude metadata files
+                .filter(key -> !key.startsWith(".z"))
                 .toArray(String[]::new);
 
             if (chunkFiles.length == 0) {

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

@@ -171,7 +171,14 @@ public ArrayMetadata build() throws ZarrException {
 
     /**
      * Calculate default chunk shape when not specified.
-     * Similar to JZarr's ArrayParams.build() logic, targeting chunks of about size 512.
+     * This implements JZarr's ArrayParams.build() logic, targeting chunks of approximately 512 elements.
+     * 
+     * The algorithm divides each dimension by 512 to determine the number of ~512-sized chunks,
+     * then calculates chunk sizes that will cover the dimension. Note that the total coverage
+     * may slightly exceed the dimension size (e.g., for shape=1024, chunks=342 results in 
+     * 3 chunks covering 1026 elements). This is intentional and matches JZarr behavior - 
+     * Zarr handles out-of-bounds gracefully, and the goal is approximate chunk sizes rather 
+     * than perfect tiling.
      */
     private int[] calculateDefaultChunks(long[] shape) {
         int[] chunks = new int[shape.length];