Virtual Disk doc fix typos and minor rewrites

src/net/torvald/terrarum/savegame/VirtualDisk.kt

@@ -24,10 +24,10 @@ current specversion number: 254
 Version 254 is a customised version of TEVD tailored to be used as a savegame format for Terrarum.
 
 ### 254
-- Removed compressed file; instead we're providing compression tool
-- Footer moved upto the header (thus freeing the entry id 0xFEFEFEFE)
+- Removed Compressed File; a compression tool is provided instead
+- Footer moved up to the header (thus freeing the entry id 0xFEFEFEFE)
 - Entry IDs are extended to 8 bytes
-- Removed file name field
+- Removed the file name field
 
 ### 0x03
 - Option to compress file entry
@@ -37,7 +37,7 @@ Version 254 is a customised version of TEVD tailored to be used as a savegame fo
 - 8 Reserved footer
 
 ### 0x01
-**Note: this version were never released in public**
+**Note: this version was never released to public**
 - Doubly Linked List instead of Singly
 
 
@@ -58,29 +58,29 @@ Version 254 is a customised version of TEVD tailored to be used as a savegame fo
 
 
 ##  Header
-    Uint8[4]    Magic: TEVd
+    UInt8[4]    Magic: TEVd
     Int48       Disk size in bytes (max 256 TiB)
-    Uint8[32]   Disk name
+    UInt8[32]   Disk name
     Int32       CRC-32
-                1. create list of arrays that contains CRC
-                2. put all the CRCs of entries
-                3. sort the list (here's the catch -- you will treat CRCs as SIGNED integer)
-                4. for elems on list: update crc with the elem (crc = calculateCRC(crc, elem))
-    Int8        Version
-    Int8        0xFE
-    < BEGIN extraInfoBytes >
+                  1. create list of arrays that contains CRC
+                  2. put all the CRCs of entries
+                  3. sort the list (here's the catch -- you will treat CRCs as SIGNED integer)
+                  4. for elems on list: update crc with the elem (crc = calculateCRC(crc, elem))
+    Int8        Version (0xFE) ----- alongside the Marker Byte, these 2 bytes are designed to raise errors when
+    Int8        Marker Byte (0xFE) - the disk archive was read by the previous versions of the implementation.
+    /* BEGIN extraInfoBytes */
     Int8        Disk properties flag 1
-                0th bit: readonly
-    Int8        Save type
-                  0th bit: unset - full save; set - quick save
-                  1st bit: set - generated by autosave
+                  0th bit: readonly
+    Int8        Save type (0b 0000 00ab)
+                  b: unset - full save; set - quick save
+                  a: set - generated by autosave
     Int8        Kind of the Save file
-                  0: Undefined (old version of the game?)
+                  0: Undefined (or very old version of the game)
                   1: Player Data
                   2: World Data
-    Int8[13]    Extra info bytes
-    < END extraInfoBytes >
-    Unit8[236]  Rest of the long disk name (268 bytes total)
+    Int8[13]    Extra info bytes reserved for future usage
+    /* END extraInfoBytes */
+    UInt8[236]  Rest of the long disk name (268 bytes total)
 
     (Header size: 300 bytes)
 
@@ -91,18 +91,18 @@ Version 254 is a customised version of TEVD tailored to be used as a savegame fo
     <Actual Entry>
 
 NOTES:
-- entries are not guaranteed to be sorted, even though the disk cracker will make it sorted.
+- entries are not guaranteed to be sorted, even though the Disk Cracker will show them sorted.
 - Root entry (ID=0) however, must be the first entry that comes right after the header.
-- Parent node of the root is undefined; do not make an assumption that root node's parent is 0.
+- Parent node of the root is undefined; do not make an assumption that parent of the root node is 0.
 
 ###  Entry Header
     Int64       EntryID (random Long). This act as "jump" position for directory listing.
-                NOTE: Index 0 must be a root "Directory"
+                  NOTE: Index 0 must be a root "Directory"
     Int64       EntryID of parent directory
-    UInt8       Flag for file or directory or symlink
-                0b d000 00tt, where:
-                tt - 0x01: Normal file, 0x02: Directory list, 0x03: Symlink
-                d - discard the entry if the bit is set
+    UInt8       Type Marker
+                  0b d000 00tt, where:
+                  tt: 01—Normal file, 10—Directory list, 11—Symlink
+                  d: discard the entry if the bit is set
     UInt8[3]    <Reserved>
     Int48       Creation date in real-life UNIX timestamp
     Int48       Last modification date in real-life UNIX timestamp
@@ -110,14 +110,14 @@ NOTES:
 
     (Header size: 36 bytes)
 
-###  Entry of File (Uncompressed)
+###  Entry of File
     Int48       File size in bytes (max 256 TiB)
     <Bytes>     Actual Contents
 
     (Header size: 6 bytes)
 
 ###  Entry of Directory
-    Uint32      Number of entries (normal files, other directories, symlinks)
+    UInt32      Number of entries (normal files, other directories, symlinks)
     <Int64s>    Entry listing, contains IndexNumber
 
     (Header size: 4 bytes)