style: update comments for consistency and clarity across multiple files

Author: DemonHashira

README.md

@@ -31,7 +31,7 @@ timetree status
 
 ## Installation
 
-**Prerequisites:** Java JDK 11 or higher (Java 21 recommended - latest LTS version). Check with:
+**Prerequisites:** Java JDK 11 or higher (Java 21 recommended). Note: Java 25 does not work due to Gradle compatibility issues. Check with:
 ```bash
 java -version
 ```
@@ -59,6 +59,8 @@ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 
 ## Commands
 
+### Core Version Control
+
 | Command | Description |
 |---------|-------------|
 | `init` | Initialize a new repository |
@@ -72,6 +74,15 @@ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 | `branch -d <name>` | Delete a branch |
 | `checkout <branch>` | Switch branches |
 
+### Low-Level Commands
+
+| Command | Description |
+|---------|-------------|
+| `hash-object <path>` | Compute object hash for a file |
+| `sig <basis> [-o output] [-b block-size]` | Generate signature for delta compression |
+| `delta <signature> <target> [-o output]` | Create delta from signature and target |
+| `patch <basis> <delta> [-o output]` | Apply delta to reconstruct file |
+
 **Alias**: Use `tt` instead of `timetree` for shorter commands.
 
 ## Architecture
@@ -101,12 +112,6 @@ TimeTree stores project history in a `.timetree/` directory:
 .\scripts\powershell\uninstall.ps1
 ```
 
-## Building from Source
-
-```bash
-./gradlew shadowJar
-```
-
 The JAR will be in `build/libs/timetree.jar`
 
 ## Testing

src/main/kotlin/dev/kamisama/cli/commands/BranchCmd.kt

@@ -33,10 +33,12 @@ class BranchCmd(
             delete && branchName != null -> {
                 deleteBranch(repo, branchName!!)
             }
+
             // Create branch
             branchName != null -> {
                 createBranch(repo, branchName!!)
             }
+
             // List branches
             else -> {
                 listBranches(repo)

src/main/kotlin/dev/kamisama/cli/commands/HashObjectCmd.kt

@@ -9,8 +9,7 @@ import java.nio.file.Files
 import java.nio.file.Paths
 
 /**
- * Diagnostic command: prints the SHA-1 ids using
- * (a) git-style header and (b) TimeTree domain-separated header.
+ * Computes the object hash for a file in both Git-style and TimeTree-style.
  */
 class HashObjectCmd :
     CliktCommand(
@@ -25,11 +24,11 @@ class HashObjectCmd :
         require(Files.isRegularFile(p)) { "Not a regular file: $p" }
         val bytes = Files.readAllBytes(p)
 
-        // a) Git-style: "blob <size>\\0" + content
+        // Git-style: "blob <size>\\0" + content
         val gitHeader = "blob ${bytes.size}\u0000".toByteArray()
         val gitId = HashAlgorithm.computeAll(gitHeader + bytes).toHex()
 
-        // b) TimeTree-style: "timetree:v1\\0blob <size>\\0" + content
+        // TimeTree-style: "timetree:v1\\0blob <size>\\0" + content
         val ttHeader = ObjectHeaders.blobHeader(bytes.size.toLong())
         val ttId = HashAlgorithm.computeAll(ttHeader + bytes).toHex()
 

src/main/kotlin/dev/kamisama/core/checkout/Checkout.kt

@@ -80,7 +80,10 @@ object Checkout {
                 if (path.startsWith(meta)) return@forEach
 
                 when {
-                    Files.isRegularFile(path) -> Files.delete(path)
+                    Files.isRegularFile(path) -> {
+                        Files.delete(path)
+                    }
+
                     Files.isDirectory(path) && path != root && path != meta -> {
                         directoriesToRemove.add(path)
                     }

src/main/kotlin/dev/kamisama/core/delta/RsyncDelta.kt

@@ -47,6 +47,7 @@ class RsyncDelta(
         return Signature(blockSize, blocks)
     }
 
+    // Creates a delta for a given signature.
     override fun makeDelta(
         target: InputStream,
         sig: Signature,
@@ -110,6 +111,7 @@ class RsyncDelta(
         return Delta(sig.blockSize, coalesceOps(ops))
     }
 
+    // Applies a delta to a basis file.
     override fun applyDelta(
         basisPath: Path,
         delta: Delta,
@@ -144,6 +146,7 @@ class RsyncDelta(
         }
     }
 
+    // Creates a delta for an empty signature.
     private fun makeDeltaForEmptySignature(
         target: InputStream,
         blockSize: Int,
@@ -241,6 +244,7 @@ class RsyncDelta(
         }
     }
 
+    // Initializes the rolling window with a single byte.
     private fun initWindowWithByte(
         byte: Byte,
         window: RingBuffer,
@@ -250,6 +254,7 @@ class RsyncDelta(
         roller.init(byteArrayOf(byte), 0, 1)
     }
 
+    // Fills the rolling window up to block size.
     private fun fillWindow(
         target: InputStream,
         window: RingBuffer,

src/main/kotlin/dev/kamisama/core/delta/io/BinaryIO.kt

@@ -8,7 +8,7 @@ import java.io.OutputStream
  * Binary I/O utilities for delta serialization.
  */
 internal object BinaryIO {
-    /** Writes 32-bit integer in big-endian format. */
+    // Writes 32-bit integer in big-endian format.
     fun writeU32(
         out: OutputStream,
         value: Int,
@@ -19,7 +19,7 @@ internal object BinaryIO {
         out.write(value and 0xFF)
     }
 
-    /** Reads 32-bit integer in big-endian format. */
+    // Reads 32-bit integer in big-endian format.
     fun readU32(input: InputStream): Int {
         val b0 = input.read()
         val b1 = input.read()
@@ -31,7 +31,7 @@ internal object BinaryIO {
         return (b0 shl 24) or (b1 shl 16) or (b2 shl 8) or b3
     }
 
-    /** Reads exact byte count from the stream. */
+    // Reads exact byte count from the stream.
     fun readBytes(
         input: InputStream,
         count: Int,

src/main/kotlin/dev/kamisama/core/delta/io/DeltaIO.kt

@@ -17,7 +17,7 @@ object DeltaIO {
     private const val MAX_OPS = 10_000_000
     private const val MAX_INSERT_LENGTH = 100 * 1024 * 1024
 
-    /** Writes delta to the output stream in binary format. */
+    // Writes delta to the output stream in binary format.
     fun write(
         delta: Delta,
         out: OutputStream,
@@ -43,7 +43,7 @@ object DeltaIO {
         }
     }
 
-    /** Reads delta from input stream. */
+    // Reads delta from input stream.
     fun read(input: InputStream): Delta {
         val magic = BinaryIO.readBytes(input, 5)
         if (!magic.contentEquals(MAGIC)) {
@@ -86,7 +86,9 @@ object DeltaIO {
                     ops.add(DeltaOp.Copy(offset, length.toInt()))
                 }
 
-                else -> throw IllegalArgumentException("Unknown delta op tag: $tag")
+                else -> {
+                    throw IllegalArgumentException("Unknown delta op tag: $tag")
+                }
             }
         }
 

src/main/kotlin/dev/kamisama/core/delta/io/SignatureIO.kt

@@ -12,7 +12,7 @@ import java.io.OutputStream
 object SignatureIO {
     private val MAGIC = byteArrayOf('T'.code.toByte(), 'T'.code.toByte(), 'S'.code.toByte(), 'G'.code.toByte(), 0x01)
 
-    /** Writes signature to the output stream. */
+    // Writes signature to the output stream.
     fun write(
         sig: Signature,
         out: OutputStream,
@@ -28,7 +28,7 @@ object SignatureIO {
         }
     }
 
-    /** Reads signature from the input stream. */
+    // Reads signature from the input stream.
     fun read(input: InputStream): Signature {
         val magic = BinaryIO.readBytes(input, 5)
         if (!magic.contentEquals(MAGIC)) {

src/main/kotlin/dev/kamisama/core/delta/io/VarInt.kt

@@ -8,7 +8,7 @@ import java.io.OutputStream
  * Base-128 variable-length integer encoding for compact storage.
  */
 object VarInt {
-    /** Encodes long value as base-128 varint. */
+    // Encodes long value as base-128 varint.
     fun write(
         out: OutputStream,
         value: Long,
@@ -21,7 +21,7 @@ object VarInt {
         out.write((v and 0x7F).toInt())
     }
 
-    /** Decodes base-128 varint from input stream. */
+    // Decodes base-128 varint from input stream.
     fun read(input: InputStream): Long {
         var result = 0L
         var shift = 0

src/main/kotlin/dev/kamisama/core/refs/Refs.kt

@@ -32,7 +32,7 @@ object Refs {
         }
     }
 
-    // Ensure HEAD points to the given branch ref (used on the first commit in fresh repo).
+    // Ensure HEAD points to the given branch ref.
     fun ensureHeadOn(
         repo: RepoLayout,
         branchRef: String = "refs/heads/master",