From 33d9ffa3bf5ebeb3c655266bb99c9133b977c39b Mon Sep 17 00:00:00 2001 From: Matthias Andreas Benkard Date: Tue, 25 Jan 2022 07:52:44 +0100 Subject: Improve the readability of the OSTree repository documentation. Change-Id: I2d8a77a146951dcb39f569e0fb285deb2fe093d5 --- .../eu/mulk/jgvariant/ostree/package-info.java | 255 ++++++++------------- 1 file changed, 93 insertions(+), 162 deletions(-) diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/package-info.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/package-info.java index 028f4cd..7ff12f7 100644 --- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/package-info.java +++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/package-info.java @@ -7,178 +7,109 @@ * *

An OSTree repository has the following layout: * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
OSTree repository layout
{@code config} - *

- * A plain text file that contains various settings. Among other things, this defines - * the archive - * format of the repository and whether files are compressed ({@code mode=archive-z2}) - * or plain ({@code mode=bare}, {@code mode=bare-user}). - *

- *
{@code summary} - *

- * A {@link eu.mulk.jgvariant.ostree.Summary} object containing information on what is - * available under {@code refs/}, {@code deltas/}, and {@code delta-indexes/}. - *

- * - *

This file may or may not exist and, if it exists, may or may not be up to date.

- *
{@code refs/heads/{name...}}Plain-text files containing {@link eu.mulk.jgvariant.ostree.Checksum}s in hex format - * (see {@link eu.mulk.jgvariant.ostree.Checksum#ofHex}) referring to - * {@link eu.mulk.jgvariant.ostree.Commit} objects. See below for the layout of the - * {@code objects/} directory that this refers to.
{@code objects/{checksumHead}/{checksumRest}.{fileExtension}} - *

- * Objects of various types as described by {@link eu.mulk.jgvariant.ostree.ObjectType} - * and keyed by {@link eu.mulk.jgvariant.ostree.Checksum}. - *

- * - *

- * Among other things, this is where you find {@link eu.mulk.jgvariant.ostree.Commit} - * ({@code .commit)}, {@link eu.mulk.jgvariant.ostree.DirTree} ({@code .dirtree}), - * and {@link eu.mulk.jgvariant.ostree.DirMeta} ({@code .dirmeta}) objects as well as - * plain ({@code .file}) or compressed files ({@code .filez}). - *

- * - *

- * Static delta information is not stored here, but in the {@code deltas/} and - * {@code delta-indexes/} directories (if available). - *

- * - *

- * The individual parts of the file path are defined as follows: - *

- * + *
+ *
{@code config} + *
+ *

A plain text file that contains various settings. Among other things, this defines the + * archive format + * of the repository and whether files are compressed ({@code mode=archive-z2}) or plain + * ({@code mode=bare}, {@code mode=bare-user}). + *

{@code summary} + *
+ *

A {@link eu.mulk.jgvariant.ostree.Summary} object containing information on what is + * available under {@code refs/}, {@code deltas/}, and {@code delta-indexes/}. + *

This file may or may not exist and, if it exists, may or may not be up to date. + *

{@code refs/heads{/name...}} + *
+ *

Plain-text files containing {@link eu.mulk.jgvariant.ostree.Checksum}s in hex format + * (see {@link eu.mulk.jgvariant.ostree.Checksum#ofHex}) referring to {@link + * eu.mulk.jgvariant.ostree.Commit} objects. See below for the layout of the {@code objects/} + * directory that this refers to. + *

{@code objects/{ξ₀ξ₁}/{ξ₂ξ₃ξ₄ξ₅...}.{ext}} + *
+ *

Objects of various types as described by {@link eu.mulk.jgvariant.ostree.ObjectType} and + * keyed by {@link eu.mulk.jgvariant.ostree.Checksum}. + *

Among other things, this is where you find {@link eu.mulk.jgvariant.ostree.Commit} + * ({@code .commit)}, {@link eu.mulk.jgvariant.ostree.DirTree} ({@code .dirtree}), and {@link + * eu.mulk.jgvariant.ostree.DirMeta} ({@code .dirmeta}) objects as well as plain ({@code + * .file}) or compressed files ({@code .filez}). + *

Static delta information is not stored here, but in the {@code deltas/} and {@code + * delta-indexes/} directories (if available). + *

The individual parts of the file path are defined as follows: *

- *
{@code {checksumHead}} - *
- * the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#hex()} - *
{@code {checksumRest}} - *
- * the substring of {@link eu.mulk.jgvariant.ostree.Checksum#hex()} starting from the - * 3rd character - *
{@code {fileExtension}} - *
- * the {@link eu.mulk.jgvariant.ostree.ObjectType#fileExtension()} of the object type + *
{@code {ξ₀ξ₁}} + *
the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#hex()} + *
{@code {ξ₂ξ₃ξ₄ξ₅...}} + *
the substring of {@link eu.mulk.jgvariant.ostree.Checksum#hex()} starting from the + * 3rd character + *
{@code {ext}} + *
the {@link eu.mulk.jgvariant.ostree.ObjectType#fileExtension()} of the object type *
- *
{@code deltas/{targetChecksumMbase64Head}/{targetChecksumMbase64Rest}/superblock} - *

- * A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from nothing (an empty commit) - * to the commit named by the checksum encoded in the path. - *

- * - *

- * The individual parts of the file path are defined as follows: - *

- * + *
{@code objects/{μ₀μ₁}/{μ₂μ₃μ₄μ₅...}.{ext}}/superblock + *
+ *

A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from nothing (an empty commit) + * to the commit named by the checksum encoded in the path. + *

The individual parts of the file path are defined as follows: *

- *
{@code {checksumHead}} - *
- * the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} - *
{@code {checksumRest}} - *
- * the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting - * from the 3rd character + *
{@code {μ₀μ₁}} + *
the first two characters of {@link + * eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target commit the delta + * ends at + *
{@code {μ₂μ₃μ₄μ₅...}} + *
the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the + * target commit the delta ends at starting from the 3rd character *
- *
{@code deltas/{targetChecksumMbase64Head}/{targetChecksumMbase64Rest}/{digit...}} - *

- * A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from - * nothing (an empty commit) to the commit named by the checksum encoded in the path. - *

- * - *

- * The individual parts of the file path are defined as follows: - *

- * + *
{@code deltas/{ν₀ν₁}/{ν₂ν₃ν₄ν₅...}/{digit...}} + *
+ *

A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from + * nothing (an empty commit) to the commit named by the checksum encoded in the path. + *

The individual parts of the file path are defined as follows: *

- *
{@code {checksumHead}} - *
- * the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} - *
{@code {checksumRest}} - *
- * the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting - * from the 3rd character + *
{@code {ν₀ν₁}} + *
the first two characters of {@link + * eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target commit the delta + * ends at + *
{@code {ν₂ν₃ν₄ν₅...}} + *
the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the + * target commit the delta ends at starting from the 3rd character *
- *
{@code deltas/{sourceChecksumMbase64Head}/{sourceChecksumMbase64Rest}-{targetChecksumMbase64}/superblock} - *

- * A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from the source commit - * referenced by the first checksum encoded in the path to the target commit referenced - * in the second checksum encoded in the path. - *

- * - *

- * The individual parts of the file path are defined as follows: - *

- * + *
{@code deltas/{μ₀μ₁}/{μ₂μ₃μ₄μ₅...}-{ν₀ν₁ν₂ν₃ν₄ν₅...}/superblock} + *
+ *

A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from the source commit + * referenced by the first checksum encoded in the path to the target commit referenced in the + * second checksum encoded in the path. + *

The individual parts of the file path are defined as follows: *

- *
{@code {checksumHead}} - *
- * the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} - *
{@code {checksumRest}} - *
- * the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting - * from the 3rd character + *
{@code {μ₀μ₁}} + *
the first two characters of {@link + * eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the source commit the delta + * starts from + *
{@code {μ₂μ₃μ₄μ₅...}} + *
the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the + * source commit the delta starts from starting from the 3rd character + *
{@code {ν₀ν₁ν₂ν₃ν₄ν₅...}} + *
the full {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target + * commit the delta ends at *
- *
{@code deltas/{sourceChecksumMbase64Head}/{sourceChecksumMbase64Rest}-{targetChecksumMbase64}/{digit...}} - *

- * A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from - * the source commit referenced by the first checksum encoded in the path to the target - * commit referenced in the second checksum encoded in the path. - *

- * - *

- * The individual parts of the file path are defined as follows: - *

- * + *
{@code deltas/{μ₀μ₁}/{μ₂μ₃μ₄μ₅...}-{ν₀ν₁ν₂ν₃ν₄ν₅...}/{digit...}} + *
+ *

A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from + * the source commit referenced by the first checksum encoded in the path to the target commit + * referenced in the second checksum encoded in the path. + *

The individual parts of the file path are defined as follows: *

- *
{@code {checksumHead}} - *
- * the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} - *
{@code {checksumRest}} - *
- * the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting - * from the 3rd character + *
{@code {μ₀μ₁}} + *
the first two characters of {@link + * eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the source commit the delta + * starts from + *
{@code {μ₂μ₃μ₄μ₅...}} + *
the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the + * source commit the delta starts from starting from the 3rd character + *
{@code {ν₀ν₁ν₂ν₃ν₄ν₅...}} + *
the full {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target + * commit the delta ends at *
- *
+ * */ @API(status = Status.EXPERIMENTAL) package eu.mulk.jgvariant.ostree; -- cgit v1.2.3