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;