From: senhuang42 <senhuang96@fb.com>
Date: Tue, 27 Oct 2020 21:45:23 +0000 (-0400)
Subject: Clarify comments in zstd.h some more
X-Git-Tag: v1.4.7~39^2~5
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3ed5d053d8ed13f5eeb569c01771ea990ead07c8;p=thirdparty%2Fzstd.git

Clarify comments in zstd.h some more
---

diff --git a/lib/common/zstd_internal.h b/lib/common/zstd_internal.h
index f9972766d..48a2a7b53 100644
--- a/lib/common/zstd_internal.h
+++ b/lib/common/zstd_internal.h
@@ -359,7 +359,7 @@ typedef struct {
 
     /* longLengthPos and longLengthID to allow us to represent either a single litLength or matchLength
      * in the seqStore that has a value larger than U16 (if it exists). To do so, we increment
-     * the existing value of the literal or match by 0x10000. 
+     * the existing value of the litLength or matchLength by 0x10000. 
      */
     U32   longLengthID;   /* 0 == no longLength; 1 == Represent the long literal; 2 == Represent the long match; */
     U32   longLengthPos;  /* Index of the sequence to apply long length modification to */
diff --git a/lib/compress/zstd_compress.c b/lib/compress/zstd_compress.c
index e2a80accd..5cd243a69 100644
--- a/lib/compress/zstd_compress.c
+++ b/lib/compress/zstd_compress.c
@@ -2480,9 +2480,6 @@ static void ZSTD_copyBlockSequences(ZSTD_CCtx* zc)
                 }
             }
             assert(repIdx >= -3);
-            /* Use default repcodes if repcode references an offset that doesn't exist yet 
-             * This can only occur within the first two sequences.
-             */
             outSeqs[i].offset = repIdx >= 0 ? outSeqs[repIdx].offset : repStartValue[-repIdx - 1];
             if (outSeqs[i].rep == 3 && outSeqs[i].litLength == 0) {
                 --outSeqs[i].offset;
@@ -2493,6 +2490,7 @@ static void ZSTD_copyBlockSequences(ZSTD_CCtx* zc)
     }
 
     /* Insert last literals (if any exist) in the block as a sequence with ml == off == 0 */
+    assert(seqStoreLiteralsSize >= literalsRead);
     lastLLSize = seqStoreLiteralsSize - literalsRead;
     if (lastLLSize > 0) {
         outSeqs[i].litLength = lastLLSize;
diff --git a/lib/zstd.h b/lib/zstd.h
index 0c243e017..b57e1de0f 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -1114,20 +1114,25 @@ ZSTDLIB_API size_t ZSTD_sizeof_DDict(const ZSTD_DDict* ddict);
 typedef struct ZSTD_CCtx_params_s ZSTD_CCtx_params;
 
 typedef struct {
-    unsigned int offset;      /* The offset of the match.
-                               * If offset == 0 and matchLength == 0,
-                               * then this sequence represents last literals in the block of litLength size.
+    unsigned int offset;      /* The offset of the match. (NOT the same as the offset code)
+                               * If offset == 0 and matchLength == 0, this sequence represents the last
+                               * literals in the block of litLength size.
                                */
 
     unsigned int litLength;   /* Literal length of the sequence. */
     unsigned int matchLength; /* Match length of the sequence. */
 
                               /* Note: Users of this API may provide a sequence with matchLength == litLength == offset == 0.
-                               * In this case, we will treat the "sequence" as a marker for a block boundary.
+                               * In this case, we will treat the sequence as a marker for a block boundary.
                                */
     
-    unsigned int rep;         /* Represents which repeat offset is used. Ranges from [0, 3].
-                               * If rep == 0, then this sequence does not contain a repeat offset.
+    unsigned int rep;         /* Represents which repeat offset is represented by the field 'offset'.
+                               * Ranges from [0, 3].
+                               * 
+                               * Repeat offsets are essentially previous offsets from previous sequences sorted in
+                               * recency order. For more detail, see doc/zstd_compression_format.md
+                               * 
+                               * If rep == 0, then 'offset' does not contain a repeat offset.
                                * If rep > 0:
                                *  If litLength != 0:
                                *      rep == 1 --> offset == repeat_offset_1
@@ -1137,6 +1142,10 @@ typedef struct {
                                *      rep == 1 --> offset == repeat_offset_2
                                *      rep == 2 --> offset == repeat_offset_3
                                *      rep == 3 --> offset == repeat_offset_1 - 1
+                               * 
+                               * Note: This field is optional. ZSTD_getSequence() will calculate the value of
+                               * 'rep', but repeat offsets do not necessarily need to be calculated from an external
+                               * sequence provider's perspective.
                                */
 } ZSTD_Sequence;