Properly document jgvariant-ostree.

Change-Id: I0aa3b1df512ef99d0e25d73efdd34a1b488e7d0d

17 files changed, 554 insertions, 18 deletions

diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/ByteString.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/ByteString.java
index 1a85547..cf6e99a 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/ByteString.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/ByteString.java
@@ -3,15 +3,24 @@ package eu.mulk.jgvariant.ostree;
 import eu.mulk.jgvariant.core.Decoder;
 import java.util.Arrays;
 import java.util.HexFormat;
+import java.util.stream.IntStream;
+import java.util.stream.Stream;
 
 /**
  * A wrapper for a {@code byte[]} that implements {@link #equals(Object)}, {@link #hashCode()}, and
  * {@link #toString()} according to value semantics.
+ *
+ * @param bytes the byte array that this ByteString wraps.
  */
 public record ByteString(byte[] bytes) {
 
   private static final Decoder<ByteString> DECODER = Decoder.ofByteArray().map(ByteString::new);
 
+  /**
+   * Returns a decoder for a {@code byte[]} that wraps the result in {@link ByteString}.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<ByteString> decoder() {
     return DECODER;
   }
@@ -31,11 +40,42 @@ public record ByteString(byte[] bytes) {
     return "ByteString{hex=\"%s\"}".formatted(hex());
   }
 
+  /**
+   * Converts the contained byte array into a hex string.
+   *
+   * <p>Useful for printing.
+   *
+   * @return a hex string representation of this byte string.
+   */
   public String hex() {
     return HexFormat.of().formatHex(bytes);
   }
 
+  /**
+   * Parses a hex string into a {@link ByteString}.
+   *
+   * @param hex a hex string.
+   * @return a {@link ByteString} corresponding to the given hex string.
+   */
   public static ByteString ofHex(String hex) {
     return new ByteString(HexFormat.of().parseHex(hex));
   }
+
+  /**
+   * Returns the number of bytes in the byte string.
+   *
+   * @return the number of bytes in the byte string.
+   */
+  public int size() {
+    return bytes.length;
+  }
+
+  /**
+   * Returns a {@link Stream} of all the bytes in the byte string.
+   *
+   * @return a new {@link Stream}.
+   */
+  Stream<Byte> stream() {
+    return IntStream.range(0, bytes.length).mapToObj(i -> bytes[i]);
+  }
 }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Checksum.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Checksum.java
index f77eb57..705e27c 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Checksum.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Checksum.java
@@ -1,24 +1,85 @@
 package eu.mulk.jgvariant.ostree;
 
 import eu.mulk.jgvariant.core.Decoder;
+import java.nio.ByteBuffer;
 
 /**
  * A wrapper for {@link ByteString} that refers to a content-addressed object in an OSTree
  * repository.
+ *
+ * @param byteString the bytes that make up this {@link Checksum}.
  */
-public record Checksum(ByteString bytes) {
+public record Checksum(ByteString byteString) {
+
+  private static final int SIZE = 32;
 
   private static final Decoder<Checksum> DECODER = ByteString.decoder().map(Checksum::new);
 
+  public Checksum {
+    if (byteString.size() != SIZE) {
+      throw new IllegalArgumentException(
+          "attempted to construct Checksum of length %d (expected: %d)"
+              .formatted(byteString.size(), SIZE));
+    }
+  }
+
+  /**
+   * A decoder for a {@code byte[]} that wraps the result in a {@link Checksum}.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<Checksum> decoder() {
     return DECODER;
   }
 
+  /**
+   * Returns an empty checksum.
+   *
+   * @return a checksum whose bits are all zero.
+   */
+  public static Checksum zero() {
+    return new Checksum(new ByteString(new byte[SIZE]));
+  }
+
+  /**
+   * Checks whether the checksum contains only zero bits.
+   *
+   * @return {@code true} if the byte string is equal to {@link #zero()}, {@code false} otherwise.
+   */
+  public boolean isEmpty() {
+    return equals(zero());
+  }
+
+  /**
+   * Converts the contained byte array into a hex string.
+   *
+   * <p>Useful for printing.
+   *
+   * @return a hex string representation of the bytes making up this checksum.
+   */
   public String hex() {
-    return bytes.hex();
+    return byteString.hex();
   }
 
+  /**
+   * Parses a hex string into a {@link Checksum}.
+   *
+   * @param hex a hex string.
+   * @return a {@link Checksum} corresponding to the given hex string.
+   */
   public static Checksum ofHex(String hex) {
     return new Checksum(ByteString.ofHex(hex));
   }
+
+  /**
+   * Reads a Checksum for a {@link ByteBuffer}.
+   *
+   * @param byteBuffer the byte buffer to read from.
+   * @return a checksum.
+   */
+  public static Checksum readFrom(ByteBuffer byteBuffer) {
+    var bytes = new byte[SIZE];
+    byteBuffer.get(bytes);
+    return new Checksum(new ByteString(bytes));
+  }
 }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Commit.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Commit.java
index 43909ba..a250937 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Commit.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Commit.java
@@ -11,6 +11,19 @@ import java.util.List;
  * <p>Has an optional parent, a root directory, and various metadata.
  *
  * <p>Reference: {@code ostree-core.h#OSTREE_COMMIT_GVARIANT_STRING}
+ *
+ * @param metadata arbitrary metadata supplied by the user who made the commit.
+ * @param parentChecksum a (possibly {@link Checksum#isEmpty()}) reference to this commit's parent
+ *     commit.
+ * @param relatedObjects references to related commits.
+ * @param subject the subject line part of the commit message.
+ * @param body the body part of the commit message.
+ * @param timestamp UNIX epoch seconds of when the commit was done.
+ * @param rootDirTreeChecksum the checksum of the {@link DirTree} file describing the root
+ *     directory.
+ * @param rootDirMetaChecksum the checksum of the {@link DirMeta} file describing the root
+ *     directory.
+ * @see ObjectType#COMMIT
  */
 public record Commit(
     Metadata metadata,
@@ -22,6 +35,12 @@ public record Commit(
     Checksum rootDirTreeChecksum,
     Checksum rootDirMetaChecksum) {
 
+  /**
+   * A reference to a related commit.
+   *
+   * @param ref the name of the reference.
+   * @param commitChecksum the checksum of the related commit.
+   */
   public record RelatedObject(String ref, Checksum commitChecksum) {
 
     private static final Decoder<RelatedObject> DECODER =
@@ -45,6 +64,11 @@ public record Commit(
           Checksum.decoder(),
           Checksum.decoder());
 
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<Commit> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaFallback.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaFallback.java
index 1b3cc0a..46470d4 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaFallback.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaFallback.java
@@ -6,19 +6,31 @@ import java.nio.ByteOrder;
 /**
  * A fallback entry in a {@link DeltaSuperblock}.
  *
+ * <p>References a file in the OSTree repository.
+ *
  * <p>Reference: {@code ostree-repo-static-delta-private.h#OSTREE_STATIC_DELTA_FALLBACK_FORMAT}
+ *
+ * @param objectType the object type of the file represented by this fallback entry.
+ * @param checksum the checksum of the file represented by this fallback entry.
+ * @param compressedSize the compressed size of the file represented by this fallback entry.
+ * @param uncompressedSize the uncompressed size of the file represented by this fallback entry.
  */
 public record DeltaFallback(
-    byte objectType, Checksum checksum, long compressedSize, long uncompressedSize) {
+    ObjectType objectType, Checksum checksum, long compressedSize, long uncompressedSize) {
 
   private static final Decoder<DeltaFallback> DECODER =
       Decoder.ofStructure(
           DeltaFallback.class,
-          Decoder.ofByte(),
+          Decoder.ofByte().map(ObjectType::valueOf),
           Checksum.decoder(),
           Decoder.ofLong().withByteOrder(ByteOrder.LITTLE_ENDIAN), // FIXME: non-canonical
           Decoder.ofLong().withByteOrder(ByteOrder.LITTLE_ENDIAN)); // FIXME: non-canonical
 
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<DeltaFallback> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaMetaEntry.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaMetaEntry.java
index 39ada86..0eaea73 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaMetaEntry.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaMetaEntry.java
@@ -1,22 +1,46 @@
 package eu.mulk.jgvariant.ostree;
 
 import eu.mulk.jgvariant.core.Decoder;
+import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
+import java.util.ArrayList;
 import java.util.List;
 
 /**
  * An entry in a {@link DeltaSuperblock}.
  *
  * <p>Reference: {@code ostree-repo-static-delta-private.h#OSTREE_STATIC_DELTA_META_ENTRY_FORMAT}
+ *
+ * @param version the version corresponding to the version of {@link DeltaPartPayload}; always 0.
+ * @param checksum the checksum of the {@link DeltaPartPayload}.
+ * @param compressedSize the total compressed size of the delta.
+ * @param uncompressedSize the total uncompressed size of the files generated by the delta.
+ * @param objects a list of objects generated by the delta payload.
  */
 public record DeltaMetaEntry(
-    int version, Checksum checksum, long size, long usize, List<DeltaObject> objects) {
+    int version,
+    Checksum checksum,
+    long compressedSize,
+    long uncompressedSize,
+    List<DeltaObject> objects) {
 
-  record DeltaObject(byte objectType, Checksum checksum) {
+  /**
+   * A reference to an object generated by a {@link DeltaPartPayload}.
+   *
+   * @param objectType the file type.
+   * @param checksum the checksum of the resulting file.
+   */
+  public record DeltaObject(ObjectType objectType, Checksum checksum) {
 
     private static final Decoder<DeltaObject> DECODER =
-        Decoder.ofStructure(DeltaObject.class, Decoder.ofByte(), Checksum.decoder());
+        Decoder.ofStructure(
+            DeltaObject.class, Decoder.ofByte().map(ObjectType::valueOf), Checksum.decoder());
 
+    /**
+     * Acquires a {@link Decoder} for the enclosing type.
+     *
+     * @return a possibly shared {@link Decoder}.
+     */
     public static Decoder<DeltaObject> decoder() {
       return DECODER;
     }
@@ -29,9 +53,26 @@ public record DeltaMetaEntry(
           Checksum.decoder(),
           Decoder.ofLong().withByteOrder(ByteOrder.LITTLE_ENDIAN), // FIXME: non-canonical
           Decoder.ofLong().withByteOrder(ByteOrder.LITTLE_ENDIAN), // FIXME: non-canonical
-          Decoder.ofByteArray().map(x -> List.of()) // FIXME
-          );
+          Decoder.ofByteArray().map(DeltaMetaEntry::parseObjectList));
+
+  private static List<DeltaObject> parseObjectList(byte[] bytes) {
+    var byteBuffer = ByteBuffer.wrap(bytes);
+    List<DeltaObject> objects = new ArrayList<>();
+
+    while (byteBuffer.hasRemaining()) {
+      var type = ObjectType.valueOf(byteBuffer.get());
+      var checksum = Checksum.readFrom(byteBuffer);
+      objects.add(new DeltaObject(type, checksum));
+    }
+
+    return objects;
+  }
 
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<DeltaMetaEntry> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaOperation.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaOperation.java
new file mode 100644
index 0000000..c1f2701
--- /dev/null
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaOperation.java
@@ -0,0 +1,53 @@
+package eu.mulk.jgvariant.ostree;
+
+import static org.apiguardian.api.API.Status.STABLE;
+
+import org.apiguardian.api.API;
+
+/** An operation in a static delta. */
+@API(status = STABLE)
+public enum DeltaOperation {
+  OPEN_SPLICE_AND_CLOSE((byte) 'S'),
+  OPEN((byte) 'o'),
+  WRITE((byte) 'w'),
+  SET_READ_SOURCE((byte) 'r'),
+  UNSET_READ_SOURCE((byte) 'R'),
+  CLOSE((byte) 'c'),
+  BSPATCH((byte) 'B');
+
+  private final byte byteValue;
+
+  DeltaOperation(byte byteValue) {
+    this.byteValue = byteValue;
+  }
+
+  /**
+   * The serialized byte value.
+   *
+   * @return a serialized byte value for use in GVariant structures.
+   */
+  public byte byteValue() {
+    return byteValue;
+  }
+
+  /**
+   * Returns the {@link DeltaOperation} corresponding to a serialized GVariant value.
+   *
+   * @param byteValue a serialized value as used in GVariant.
+   * @return the {@link DeltaOperation} corresponding to the serialized value.
+   * @throws IllegalArgumentException if the byte value is invalid.
+   */
+  public static DeltaOperation valueOf(byte byteValue) {
+    return switch (byteValue) {
+      case (byte) 'S' -> OPEN_SPLICE_AND_CLOSE;
+      case (byte) 'o' -> OPEN;
+      case (byte) 'w' -> WRITE;
+      case (byte) 'r' -> SET_READ_SOURCE;
+      case (byte) 'R' -> UNSET_READ_SOURCE;
+      case (byte) 'c' -> CLOSE;
+      case (byte) 'B' -> BSPATCH;
+      default -> throw new IllegalArgumentException(
+          "invalid DeltaOperation: %d".formatted(byteValue));
+    };
+  }
+}
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaPartPayload.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaPartPayload.java
index c8c5fe7..7f7dd23 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaPartPayload.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaPartPayload.java
@@ -5,13 +5,25 @@ import java.nio.ByteOrder;
 import java.util.List;
 
 /**
- * Reference: {@code ostree-repo-static-delta-private.h#OSTREE_STATIC_DELTA_PART_PAYLOAD_FORMAT_V0}
+ * A payload file from a static delta.
+ *
+ * <p>The first byte is a compression byte: {@code 0} for none, {@code 'x'} for LZMA. The actual
+ * GVariant data begins right after.
+ *
+ * <p>Reference: {@code
+ * ostree-repo-static-delta-private.h#OSTREE_STATIC_DELTA_PART_PAYLOAD_FORMAT_V0}
+ *
+ * @param fileModes the {@link FileMode}s of the files generated by this delta payload.
+ * @param xattrs the {@link Xattr}s of the files generated by this delta payload.
+ * @param rawDataSource the data bytes used in the delta operations.
+ * @param operations the operations to apply during delta patching.
+ * @see DeltaSuperblock
  */
 public record DeltaPartPayload(
     List<FileMode> fileModes,
     List<List<Xattr>> xattrs,
     ByteString rawDataSource,
-    ByteString operations) {
+    List<DeltaOperation> operations) {
 
   private static final Decoder<DeltaPartPayload> DECODER =
       Decoder.ofStructure(
@@ -19,8 +31,19 @@ public record DeltaPartPayload(
           Decoder.ofArray(FileMode.decoder()),
           Decoder.ofArray(Decoder.ofArray(Xattr.decoder())),
           ByteString.decoder(),
-          ByteString.decoder());
+          ByteString.decoder().map(DeltaPartPayload::parseDeltaOperationList));
 
+  private static List<DeltaOperation> parseDeltaOperationList(ByteString byteString) {
+    return byteString.stream().map(DeltaOperation::valueOf).toList();
+  }
+
+  /**
+   * A file mode triple (UID, GID, and permission bits).
+   *
+   * @param uid
+   * @param gid
+   * @param mode
+   */
   public record FileMode(int uid, int gid, int mode) {
 
     private static final Decoder<FileMode> DECODER =
@@ -30,11 +53,24 @@ public record DeltaPartPayload(
             Decoder.ofInt().withByteOrder(ByteOrder.LITTLE_ENDIAN),
             Decoder.ofInt().withByteOrder(ByteOrder.LITTLE_ENDIAN));
 
+    /**
+     * Acquires a {@link Decoder} for the enclosing type.
+     *
+     * @return a possibly shared {@link Decoder}.
+     */
     public static Decoder<FileMode> decoder() {
       return DECODER;
     }
   }
 
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * <p>FIXME: The first byte is actually a compression byte: {@code 0} for none, {@code 'x'} for
+   * LZMA.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<DeltaPartPayload> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaSuperblock.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaSuperblock.java
index 2b09645..edcf2bf 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaSuperblock.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DeltaSuperblock.java
@@ -1,10 +1,27 @@
 package eu.mulk.jgvariant.ostree;
 
 import eu.mulk.jgvariant.core.Decoder;
+import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
+import java.util.ArrayList;
 import java.util.List;
 
-/** Reference: {@code ostree-repo-static-delta-private.h#OSTREE_STATIC_DELTA_SUPERBLOCK_FORMAT} */
+/**
+ * A static delta.
+ *
+ * <p>Reference: {@code ostree-repo-static-delta-private.h#OSTREE_STATIC_DELTA_SUPERBLOCK_FORMAT}
+ *
+ * @param metadata arbitrary user-supplied metadata.
+ * @param timestamp UNIX epoch seconds of when the commit was done.
+ * @param fromChecksum a (possibly {@link Checksum#isEmpty()}) reference to the starting commit.
+ * @param toChecksum a (non-{@link Checksum#isEmpty()}) reference to the end commit.
+ * @param commit the commit metadata of the end commit.
+ * @param dependencies a list of other {@link DeltaSuperblock}s that need to be applied before this
+ *     one.
+ * @param entries a list of metadata on the {@link DeltaPartPayload}s that make up the delta.
+ * @param fallbacks a list of objects included in the delta as plain files that have to be fetched
+ *     separately.
+ */
 public record DeltaSuperblock(
     Metadata metadata,
     long timestamp,
@@ -15,11 +32,24 @@ public record DeltaSuperblock(
     List<DeltaMetaEntry> entries,
     List<DeltaFallback> fallbacks) {
 
+  /**
+   * A specifier for another static delta.
+   *
+   * <p>Used to specify {@link DeltaSuperblock#dependencies()}.
+   *
+   * @param fromChecksum the {@link DeltaSuperblock#fromChecksum()} of the referenced delta.
+   * @param toChecksum the {@link DeltaSuperblock#toChecksum()} of the referenced delta.
+   */
   public record DeltaName(Checksum fromChecksum, Checksum toChecksum) {
 
     private static final Decoder<DeltaName> DECODER =
         Decoder.ofStructure(DeltaName.class, Checksum.decoder(), Checksum.decoder());
 
+    /**
+     * Acquires a {@link Decoder} for the enclosing type.
+     *
+     * @return a possibly shared {@link Decoder}.
+     */
     public static Decoder<DeltaName> decoder() {
       return DECODER;
     }
@@ -33,10 +63,28 @@ public record DeltaSuperblock(
           Checksum.decoder(),
           Checksum.decoder(),
           Commit.decoder(),
-          Decoder.ofByteArray().map(x -> List.of()), // FIXME
+          Decoder.ofByteArray().map(DeltaSuperblock::parseDeltaNameList),
           Decoder.ofArray(DeltaMetaEntry.decoder()),
           Decoder.ofArray(DeltaFallback.decoder()));
 
+  private static List<DeltaName> parseDeltaNameList(byte[] bytes) {
+    var byteBuffer = ByteBuffer.wrap(bytes);
+    List<DeltaName> deltaNames = new ArrayList<>();
+
+    while (byteBuffer.hasRemaining()) {
+      var fromChecksum = Checksum.readFrom(byteBuffer);
+      var toChecksum = Checksum.readFrom(byteBuffer);
+      deltaNames.add(new DeltaName(fromChecksum, toChecksum));
+    }
+
+    return deltaNames;
+  }
+
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<DeltaSuperblock> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DirMeta.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DirMeta.java
index 3a9672d..35c5212 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DirMeta.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DirMeta.java
@@ -7,7 +7,19 @@ import java.util.List;
 /**
  * Permission bits and extended attributes for a directory.
  *
+ * <p>Often comes in a pair with {@link DirTree}.
+ *
+ * <p>Referenced by {@link Commit#rootDirMetaChecksum()} and {@link
+ * DirTree.Directory#dirChecksum()}.
+ *
  * <p>Reference: {@code ostree-core.h#OSTREE_DIRMETA_GVARIANT_STRING}
+ *
+ * @param uid the user ID that owns the directory.
+ * @param gid the group ID that owns the directory.
+ * @param mode the POSIX permission bits.
+ * @param xattrs POSIX extended attributes.
+ * @see DirTree
+ * @see ObjectType#DIR_META
  */
 public record DirMeta(int uid, int gid, int mode, List<Xattr> xattrs) {
 
@@ -19,6 +31,11 @@ public record DirMeta(int uid, int gid, int mode, List<Xattr> xattrs) {
           Decoder.ofInt().withByteOrder(ByteOrder.BIG_ENDIAN),
           Decoder.ofArray(Xattr.decoder()));
 
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<DirMeta> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DirTree.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DirTree.java
index 3a14abb..ef7d05f 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DirTree.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/DirTree.java
@@ -7,24 +7,49 @@ import java.util.List;
 /**
  * Metadata describing files and directories of a file tree.
  *
+ * <p>Often comes in a pair with {@link DirMeta}.
+ *
  * <p>Referenced by {@link Commit#rootDirTreeChecksum()} and recursively by {@link
  * Directory#treeChecksum()}.
  *
  * <p>Reference: {@code ostree-core.h#OSTREE_TREE_GVARIANT_STRING}
+ *
+ * @param files a list of files in the directory.
+ * @param directories a list of subdirectories of the directory.
+ * @see DirMeta
+ * @see ObjectType#DIR_TREE
  */
 public record DirTree(List<File> files, List<Directory> directories) {
 
+  /**
+   * A file in a file tree.
+   *
+   * @param name the file name.
+   * @param checksum the checksum of the {@link ObjectType#FILE} object.
+   */
   public record File(String name, Checksum checksum) {
 
     private static final Decoder<File> DECODER =
         Decoder.ofStructure(
             File.class, Decoder.ofString(StandardCharsets.UTF_8), Checksum.decoder());
 
+    /**
+     * Acquires a {@link Decoder} for the enclosing type.
+     *
+     * @return a possibly shared {@link Decoder}.
+     */
     public static Decoder<File> decoder() {
       return DECODER;
     }
   }
 
+  /**
+   * A subdirectory in a file tree.
+   *
+   * @param name the name of the subdirectory.
+   * @param treeChecksum the checksum of the {@link DirTree} object.
+   * @param dirChecksum the checksum of the {@link DirMeta} object.
+   */
   public record Directory(String name, Checksum treeChecksum, Checksum dirChecksum) {
 
     private static final Decoder<Directory> DECODER =
@@ -34,6 +59,11 @@ public record DirTree(List<File> files, List<Directory> directories) {
             Checksum.decoder(),
             Checksum.decoder());
 
+    /**
+     * Acquires a {@link Decoder} for the enclosing type.
+     *
+     * @return a possibly shared {@link Decoder}.
+     */
     public static Decoder<Directory> decoder() {
       return DECODER;
     }
@@ -43,6 +73,11 @@ public record DirTree(List<File> files, List<Directory> directories) {
       Decoder.ofStructure(
           DirTree.class, Decoder.ofArray(File.decoder()), Decoder.ofArray(Directory.decoder()));
 
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<DirTree> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/FileMeta.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/FileMeta.java
index 19e0677..2786ce9 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/FileMeta.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/FileMeta.java
@@ -7,7 +7,15 @@ import java.util.List;
 /**
  * Permission bits and extended attributes for a file.
  *
+ * <p>Stored in a POSIX extended attribute on the corresponding {@link ObjectType#FILE} object in
+ * repositories in “bare-user” format.
+ *
  * <p>Reference: {@code ostree-core.h#OSTREE_FILEMETA_GVARIANT_STRING}
+ *
+ * @param uid the user ID that owns the file.
+ * @param gid the group ID that owns the file.
+ * @param mode the POSIX permission bits.
+ * @param xattrs POSIX extended attributes.
  */
 public record FileMeta(int uid, int gid, int mode, List<Xattr> xattrs) {
 
@@ -19,6 +27,11 @@ public record FileMeta(int uid, int gid, int mode, List<Xattr> xattrs) {
           Decoder.ofInt().withByteOrder(ByteOrder.BIG_ENDIAN),
           Decoder.ofArray(Xattr.decoder()));
 
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<FileMeta> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Metadata.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Metadata.java
index 8bb5255..fd8df28 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Metadata.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Metadata.java
@@ -6,9 +6,11 @@ import java.nio.charset.StandardCharsets;
 import java.util.Map;
 
 /**
- * A wrapper for a list of metadata fields.
+ * A wrapper for a set of metadata fields.
  *
  * <p>Reference: (embedded in other data types)
+ *
+ * @param fields a set of metadata fields indexed by name.
  */
 public record Metadata(Map<String, Variant> fields) {
 
@@ -16,6 +18,11 @@ public record Metadata(Map<String, Variant> fields) {
       Decoder.ofDictionary(Decoder.ofString(StandardCharsets.UTF_8), Decoder.ofVariant())
           .map(Metadata::new);
 
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<Metadata> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/ObjectType.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/ObjectType.java
new file mode 100644
index 0000000..28371fc
--- /dev/null
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/ObjectType.java
@@ -0,0 +1,80 @@
+package eu.mulk.jgvariant.ostree;
+
+import static org.apiguardian.api.API.Status.STABLE;
+
+import org.apiguardian.api.API;
+
+/**
+ * An object type as found in an OSTree repository.
+ *
+ * <p>Each object type has its own file extension.
+ *
+ * <p>In an OSTree repository, objects are located in a subfolder of the {@code /objects} folder
+ * based on their {@link Checksum}. The schema for looking up objects is {@code
+ * /objects/{checksumHead}/{checksumRest}.{fileExtension}} where:
+ *
+ * <dl>
+ *   <dt>{@code {checksumHead}}
+ *   <dd>the first two characters of {@link Checksum#hex()}
+ *   <dt>{@code {checksumRest}}
+ *   <dd>the substring of {@link Checksum#hex()} starting from the 3rd character
+ *   <dt>{@code {fileExtension}}
+ *   <dd>the {@link #fileExtension()} of the object type
+ * </dl>
+ */
+@API(status = STABLE)
+public enum ObjectType {
+  FILE((byte) 1, "file"),
+  DIR_TREE((byte) 2, "dirtree"),
+  DIR_META((byte) 3, "dirmeta"),
+  COMMIT((byte) 4, "commit"),
+  TOMBSTONE_COMMIT((byte) 5, "commit-tombstone"),
+  COMMIT_META((byte) 6, "commitmeta"),
+  PAYLOAD_LINK((byte) 7, "payload-link");
+
+  private final byte byteValue;
+  private final String fileExtension;
+
+  /**
+   * The serialized byte value.
+   *
+   * @return a byte representing this value in serialized GVariant structures.
+   */
+  public byte byteValue() {
+    return byteValue;
+  }
+
+  /**
+   * The file extension carried by files of this type.
+   *
+   * @return a file extension.
+   */
+  public String fileExtension() {
+    return fileExtension;
+  }
+
+  ObjectType(byte byteValue, String fileExtension) {
+    this.byteValue = byteValue;
+    this.fileExtension = fileExtension;
+  }
+
+  /**
+   * Returns the {@link ObjectType} corresponding to a serialized GVariant value.
+   *
+   * @param byteValue a serialized value as used in GVariant.
+   * @return the {@link ObjectType} corresponding to the serialized value.
+   * @throws IllegalArgumentException if the byte value is invalid.
+   */
+  public static ObjectType valueOf(byte byteValue) {
+    return switch (byteValue) {
+      case 1 -> FILE;
+      case 2 -> DIR_TREE;
+      case 3 -> DIR_META;
+      case 4 -> COMMIT;
+      case 5 -> TOMBSTONE_COMMIT;
+      case 6 -> COMMIT_META;
+      case 7 -> PAYLOAD_LINK;
+      default -> throw new IllegalArgumentException("invalid ObjectType: %d".formatted(byteValue));
+    };
+  }
+}
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/SignedDelta.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/SignedDelta.java
index 303e344..0077cb4 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/SignedDelta.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/SignedDelta.java
@@ -2,6 +2,7 @@ package eu.mulk.jgvariant.ostree;
 
 import eu.mulk.jgvariant.core.Decoder;
 import eu.mulk.jgvariant.core.Variant;
+import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
 import java.nio.charset.StandardCharsets;
 import java.util.Map;
@@ -10,17 +11,33 @@ import java.util.Map;
  * A {@link DeltaSuperblock} signed with some sort of key.
  *
  * <p>Reference: {@code ostree-repo-static-delta-private.h#OSTREE_STATIC_DELTA_SIGNED_FORMAT}
+ *
+ * @param magicNumber the value {@link #MAGIC}.
+ * @param superblock the {@link DeltaSuperblock}.
+ * @param signatures a list of signatures, indexed by type.
  */
 public record SignedDelta(
-    long magicNumber, ByteString superblock, Map<String, Variant> signatures) {
+    long magicNumber, DeltaSuperblock superblock, Map<String, Variant> signatures) {
+
+  /** The value of {@link #magicNumber()}. */
+  public static final long MAGIC = 0x4F53_5453_474E_4454L;
 
   private static final Decoder<SignedDelta> DECODER =
       Decoder.ofStructure(
           SignedDelta.class,
           Decoder.ofLong().withByteOrder(ByteOrder.BIG_ENDIAN),
-          ByteString.decoder(),
+          ByteString.decoder().map(SignedDelta::decodeSuperblock),
           Decoder.ofDictionary(Decoder.ofString(StandardCharsets.US_ASCII), Decoder.ofVariant()));
 
+  private static DeltaSuperblock decodeSuperblock(ByteString byteString) {
+    return DeltaSuperblock.decoder().decode(ByteBuffer.wrap(byteString.bytes()));
+  }
+
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<SignedDelta> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Summary.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Summary.java
index 8f4ddf6..bc94436 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Summary.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Summary.java
@@ -11,11 +11,29 @@ import java.util.List;
  * <p>Stored as a file named {@code summary} in the OSTree repository root.
  *
  * <p>Reference: {@code ostree-core.h#OSTREE_SUMMARY_GVARIANT_STRING}
+ *
+ * @param entries an entry in the summary file.
+ * @param metadata additional keys and values contained in the summary.
  */
 public record Summary(List<Entry> entries, Metadata metadata) {
 
+  /**
+   * An entry in the summary file of an OSTree repository, describing a ref.
+   *
+   * @param ref a ref name.
+   * @param value data describing the ref.
+   */
   public record Entry(String ref, Value value) {
 
+    /**
+     * The value part of an entry in the summary file of an OSTree repository.
+     *
+     * <p>Describes the {@link Commit} currently named by the corresponding ref.
+     *
+     * @param size the size of the commit.
+     * @param checksum the checksum of the commit.
+     * @param metadata additional metadata describing the commit.
+     */
     public record Value(long size, Checksum checksum, Metadata metadata) {
 
       private static final Decoder<Value> DECODER =
@@ -25,6 +43,11 @@ public record Summary(List<Entry> entries, Metadata metadata) {
               Checksum.decoder(),
               Metadata.decoder());
 
+      /**
+       * Acquires a {@link Decoder} for the enclosing type.
+       *
+       * @return a possibly shared {@link Decoder}.
+       */
       public static Decoder<Value> decoder() {
         return DECODER;
       }
@@ -33,6 +56,11 @@ public record Summary(List<Entry> entries, Metadata metadata) {
     private static final Decoder<Entry> DECODER =
         Decoder.ofStructure(Entry.class, Decoder.ofString(StandardCharsets.UTF_8), Value.decoder());
 
+    /**
+     * Acquires a {@link Decoder} for the enclosing type.
+     *
+     * @return a possibly shared {@link Decoder}.
+     */
     public static Decoder<Entry> decoder() {
       return DECODER;
     }
@@ -41,6 +69,11 @@ public record Summary(List<Entry> entries, Metadata metadata) {
   private static final Decoder<Summary> DECODER =
       Decoder.ofStructure(Summary.class, Decoder.ofArray(Entry.decoder()), Metadata.decoder());
 
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<Summary> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/SummarySignature.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/SummarySignature.java
index 13bb432..efa48c3 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/SummarySignature.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/SummarySignature.java
@@ -11,6 +11,8 @@ import java.util.Map;
  * <p>Stored as a file named {@code summary.sig} in the OSTree repository root.
  *
  * <p>Reference: {@code ostree-repo-static-delta-private.h#OSTREE_SUMMARY_SIG_GVARIANT_STRING}
+ *
+ * @param signatures a list of signatures, indexed by type.
  */
 public record SummarySignature(Map<String, Variant> signatures) {
 
@@ -18,6 +20,11 @@ public record SummarySignature(Map<String, Variant> signatures) {
       Decoder.ofDictionary(Decoder.ofString(StandardCharsets.UTF_8), Decoder.ofVariant())
           .map(SummarySignature::new);
 
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<SummarySignature> decoder() {
     return DECODER;
   }
diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Xattr.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Xattr.java
index 68628c4..7f05cf6 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Xattr.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/Xattr.java
@@ -3,15 +3,27 @@ package eu.mulk.jgvariant.ostree;
 import eu.mulk.jgvariant.core.Decoder;
 
 /**
- * Reference: (embedded in other data types, e.g. {@code
+ * A POSIX extended attribute of a file or directory.
+ *
+ * <p>Reference: (embedded in other data types, e.g. {@code
  * ostree-core.h#OSTREE_DIRMETA_GVARIANT_STRING}, {@code
  * ostree-core.h#OSTREE_FILEMETA_GVARIANT_STRING})
+ *
+ * @param name the name part of the extended attribute.
+ * @param value the value part of the extended attribute.
+ * @see DirMeta
+ * @see FileMeta
  */
 public record Xattr(ByteString name, ByteString value) {
 
   private static final Decoder<Xattr> DECODER =
       Decoder.ofStructure(Xattr.class, ByteString.decoder(), ByteString.decoder());
 
+  /**
+   * Acquires a {@link Decoder} for the enclosing type.
+   *
+   * @return a possibly shared {@link Decoder}.
+   */
   public static Decoder<Xattr> decoder() {
     return DECODER;
   }