herringbone 0.2.0 → 0.3.0

data/lib/herringbone/codecs/lz4.rb

@@ -5,17 +5,26 @@ module Herringbone
     # Pure-Ruby LZ4: raw block format (Parquet LZ4_RAW), Hadoop-framed blocks
     # (Parquet's deprecated LZ4) and a decoder for the LZ4 frame format.
     module LZ4
+      # Raised for corrupt, truncated or unsupported LZ4 input.
       class Error < StandardError; end
 
+      # Shortest match a sequence can encode; the token's match length is stored minus this.
       MIN_MATCH = 4
       LAST_LITERALS = 5 # the last 5 bytes of a block are always literals
       MFLIMIT = 12      # the last match must start at least 12 bytes before the end
+      # Largest backward distance a 2-byte match offset can express.
       MAX_OFFSET = 65_535
+      # Size of the compressor's hash table, in bits (16384 entries).
       HASH_LOG = 14
+      # Right shift that keeps the top HASH_LOG bits of the 32-bit multiplicative hash.
       HASH_SHIFT = 32 - HASH_LOG
+      # Controls how fast the compressor skips ahead through input without matches (as in the reference).
       SKIP_STRENGTH = 6
+      # Magic number at the start of an LZ4 frame (little-endian).
       FRAME_MAGIC = 0x184D2204
+      # Hadoop block header: big-endian 32-bit uncompressed size and compressed size.
       HADOOP_PREFIX = 8
+      # Shorthand for Encoding::BINARY.
       BINARY = Encoding::BINARY
       # String#unpack1 accepts offset: since Ruby 3.1
       UNPACK_OFFSET = begin
@@ -28,6 +37,10 @@ module Herringbone
       module_function
 
       # Decompress a raw LZ4 block that must expand to exactly uncompressed_size bytes.
+      # @param input [String] raw LZ4 block
+      # @param uncompressed_size [Integer] exact decompressed size, from the page header
+      # @return [String] decompressed bytes in ASCII-8BIT
+      # @raise [Error] if the block is corrupt or does not decode to +uncompressed_size+ bytes
       def decompress_block(input, uncompressed_size)
         src = binary(input)
         out = String.new(capacity: uncompressed_size, encoding: BINARY)
@@ -40,6 +53,10 @@ module Herringbone
 
       # Parquet LZ4 (codec 5). Tries Hadoop framing, then the LZ4 frame format,
       # then a bare raw block (Arrow falls back hadoop -> raw; some writers emitted frames).
+      # @param input [String] compressed page data
+      # @param uncompressed_size [Integer] exact decompressed size, from the page header
+      # @return [String] decompressed bytes in ASCII-8BIT
+      # @raise [Error] if none of the three layouts decodes
       def decompress_hadoop(input, uncompressed_size)
         src = binary(input)
         result = try_hadoop(src, uncompressed_size)
@@ -58,6 +75,10 @@ module Herringbone
 
       # Decode LZ4 frame format data (one or more frames, skippable frames ignored).
       # Checksums are skipped, not verified.
+      # @param input [String] one or more concatenated LZ4 frames
+      # @param max_size [Integer] upper bound on the decompressed size
+      # @return [String] decompressed bytes in ASCII-8BIT, possibly shorter than +max_size+
+      # @raise [Error] on bad magic, truncation, unsupported frame features or output over +max_size+
       def decompress_frame(input, max_size)
         src = binary(input)
         n = src.bytesize
@@ -79,6 +100,8 @@ module Herringbone
       end
 
       # Compress into a single raw LZ4 block.
+      # @param input [String] bytes to compress
+      # @return [String] raw LZ4 block in ASCII-8BIT
       def compress_block(input)
         src = binary(input)
         n = src.bytesize
@@ -121,7 +144,7 @@ module Herringbone
             # Emit the sequence: token, literal run, offset, extended match length
             lit_len = ip - anchor
             ml = len - MIN_MATCH
-            out << (((lit_len < 15 ? lit_len : 15) << 4) | (ml < 15 ? ml : 15))
+            out << ((((lit_len < 15) ? lit_len : 15) << 4) | ((ml < 15) ? ml : 15))
             write_length(out, lit_len - 15) if lit_len >= 15
             out << src.byteslice(anchor, lit_len) if lit_len > 0
             offset = ip - ref
@@ -144,6 +167,8 @@ module Herringbone
       end
 
       # Single Hadoop-framed block: [BE uncompressed size][BE compressed size][raw block]
+      # @param input [String] bytes to compress
+      # @return [String] Hadoop-framed LZ4 data in ASCII-8BIT
       def compress_hadoop(input)
         src = binary(input)
         block = compress_block(src)
@@ -152,18 +177,31 @@ module Herringbone
 
       # -- internals --
 
+      # @param str [String] input in any encoding
+      # @return [String] +str+ itself if already binary, otherwise a binary copy
       def binary(str)
-        str.encoding == BINARY ? str : str.b
+        (str.encoding == BINARY) ? str : str.b
       end
 
+      # @param src [String] binary input
+      # @param i [Integer] byte offset
+      # @return [Integer] unsigned little-endian 32-bit value at +i+
       def le32(src, i)
         src.byteslice(i, 4).unpack1("V")
       end
 
+      # Same as le32 but via getbyte, for Rubies without unpack1(offset:).
+      # @param src [String] binary input
+      # @param i [Integer] byte offset
+      # @return [Integer] unsigned little-endian 32-bit value at +i+
       def u32(src, i)
         src.getbyte(i) | (src.getbyte(i + 1) << 8) | (src.getbyte(i + 2) << 16) | (src.getbyte(i + 3) << 24)
       end
 
+      # Appends the extension of a literal or match length: 255-bytes followed by the remainder.
+      # @param out [String] binary output buffer, appended to
+      # @param len [Integer] length minus the 15 already stored in the token
+      # @return [String] +out+
       def write_length(out, len)
         if len >= 255
           out << ("\xFF".b * (len / 255))
@@ -172,14 +210,27 @@ module Herringbone
         out << len
       end
 
+      # Appends the final, literals-only sequence that terminates every block.
+      # @param out [String] binary output buffer, appended to
+      # @param src [String] binary input
+      # @param anchor [Integer] offset of the first pending literal in +src+
+      # @param lit_len [Integer] number of trailing literal bytes (may be zero)
+      # @return [String, nil] +out+, or nil when there are no literals
       def emit_last_literals(out, src, anchor, lit_len)
-        out << ((lit_len < 15 ? lit_len : 15) << 4)
+        out << (((lit_len < 15) ? lit_len : 15) << 4)
         write_length(out, lit_len - 15) if lit_len >= 15
         out << src.byteslice(anchor, lit_len) if lit_len > 0
       end
 
       # Decode one raw block from src[ip...iend], appending to out (which may already
       # hold earlier data that matches can reference). out may not grow beyond limit.
+      # @param src [String] binary input
+      # @param ip [Integer] offset of the block in +src+
+      # @param iend [Integer] offset just past the block
+      # @param out [String] binary output buffer, appended to
+      # @param limit [Integer] maximum total byte size of +out+
+      # @return [Integer] input offset where decoding stopped
+      # @raise [Error] if the block is truncated, has an invalid offset or overflows +limit+
       def decode_block(src, ip, iend, out, limit)
         while ip < iend
           token = src.getbyte(ip)
@@ -237,6 +288,9 @@ module Herringbone
       end
 
       # Arrow-compatible Hadoop frame parsing; returns nil if the data does not fit the framing.
+      # @param src [String] binary input
+      # @param uncompressed_size [Integer] exact decompressed size expected over all blocks
+      # @return [String, nil] decompressed bytes, or nil if +src+ is not valid Hadoop-framed LZ4
       def try_hadoop(src, uncompressed_size)
         n = src.bytesize
         return nil if n < HADOOP_PREFIX
@@ -262,6 +316,15 @@ module Herringbone
         out
       end
 
+      # Decodes the descriptor and data blocks of one LZ4 frame (after its magic number),
+      # skipping content size and checksums.
+      # @param src [String] binary input
+      # @param ip [Integer] offset of the frame descriptor (just past the magic)
+      # @param n [Integer] byte size of +src+
+      # @param out [String] binary output buffer, appended to
+      # @param limit [Integer] maximum total byte size of +out+
+      # @return [Integer] offset just past the frame
+      # @raise [Error] on truncation, an unsupported version or dictionary, or output over +limit+
       def decode_frame(src, ip, n, out, limit)
         raise Error, "Truncated LZ4 frame descriptor" if ip + 3 > n
         flg = src.getbyte(ip)

data/lib/herringbone/codecs/snappy.rb

@@ -1,33 +1,103 @@
 # frozen_string_literal: true
 
 module Herringbone
+  # Pure-Ruby compression codecs for Parquet pages: Snappy, and LZ4 (raw blocks and the Hadoop framing).
+  # Compression dispatches to these; GZIP uses Zlib and ZSTD/BROTLI use external gems.
   module Codecs
     # Pure-Ruby implementation of the raw Snappy block format (as used by Parquet),
     # see https://github.com/google/snappy/blob/main/format_description.txt
     #
+    # When the `snappy` gem (a binding to Google's libsnappy) can be loaded, it is used instead:
+    # 12x faster decompression and 27x faster compression. It is optional and only a speedup: if
+    # it is missing, the pure-Ruby code below is used silently. Both produce raw Snappy blocks the
+    # other reads.
+    #
     # 32-bit loads are done with four getbyte calls rather than unpack1(offset:) to stay
     # compatible with Ruby 3.0 - the speed difference on MRI is marginal.
     module Snappy
+      # Raised for corrupt or truncated Snappy input, and for input too large to compress.
       class Error < StandardError; end
 
+      # The compressor works on independent 64 KiB fragments, as the reference implementation does.
       BLOCK_SIZE = 1 << 16
+      # Size of the match-finder hash table, in bits (16384 entries).
       HASH_BITS = 14
+      # Right shift that keeps the top HASH_BITS bits of the 32-bit multiplicative hash.
       HASH_SHIFT = 32 - HASH_BITS
+      # Multiplier of the reference implementation's 4-byte hash.
       HASH_MUL = 0x1e35a7bd
       INPUT_MARGIN = 15 # bytes at the block end never searched for matches, as in the reference
+      # The length preamble is a 32-bit varint, so no block may decompress to more than this.
       MAX_UNCOMPRESSED = (1 << 32) - 1
 
+      # Name of the optional native gem, passed to +require+.
+      NATIVE_GEM = "snappy"
+
       module_function
 
       # @param input [String] raw snappy block
       # @return [String] decompressed bytes in ASCII-8BIT
+      # @raise [Error] if the block is corrupt or truncated
       def decompress(input)
-        src = input.encoding == Encoding::BINARY ? input : input.b
+        src = (input.encoding == Encoding::BINARY) ? input : input.b
+        if (lib = native)
+          begin
+            return lib.inflate(src)
+          rescue lib::Error => e
+            raise Error, "corrupt snappy data (#{e.message})"
+          end
+        end
         return decompress_io_buffer(src) if IOBufferSupport::AVAILABLE
         decompress_string(src)
       end
 
+      # The backend in use: :native (the snappy gem) or :ruby
+      # @return [Symbol] +:native+ or +:ruby+
+      def backend
+        native ? :native : :ruby
+      end
+
+      # For tests and benchmarks: :ruby forces pure Ruby, :native requires the snappy gem
+      # (UnsupportedError if it cannot be loaded), nil goes back to the default
+      # @param name [Symbol, nil] +:ruby+, +:native+ or nil
+      # @return [void]
+      # @raise [UnsupportedError] if +:native+ is requested and the gem cannot be loaded
+      # @raise [ArgumentError] for any other backend name
+      def backend=(name)
+        @native = case name
+        when :ruby then false
+        when :native
+          native_library || raise(UnsupportedError, "The \"#{NATIVE_GEM}\" gem could not be loaded")
+        when nil then nil
+        else raise ArgumentError, "Unknown Snappy backend #{name.inspect} (expected :ruby, :native or nil)"
+        end
+      end
+
+      # The native library to use, resolved (and memoized) on first call unless forced by backend=.
+      # @return [Module, nil] the +::Snappy+ module, or nil when the pure-Ruby code should run
+      def native
+        @native = native_library || false if @native.nil?
+        @native || nil
+      end
+
+      # Tries to load the snappy gem once and memoizes the result.
+      # @return [Module, false] the +::Snappy+ module, or false if it is missing or lacks inflate/deflate
+      def native_library
+        if @native_lib.nil?
+          @native_lib = begin
+            require NATIVE_GEM
+            (::Snappy.respond_to?(:inflate) && ::Snappy.respond_to?(:deflate)) ? ::Snappy : false
+          rescue LoadError
+            false
+          end
+        end
+        @native_lib
+      end
+
       # Decompresses into a preallocated IO::Buffer: copies do not allocate intermediate Strings.
+      # @param src [String] raw snappy block in ASCII-8BIT
+      # @return [String] decompressed bytes in ASCII-8BIT
+      # @raise [Error] if the block is corrupt or truncated
       def decompress_io_buffer(src)
         n = src.bytesize
         expected, pos = read_varint(src, n)
@@ -98,6 +168,10 @@ module Herringbone
         inbuf&.free
       end
 
+      # Decompresses by appending to a String; the fallback when IO::Buffer is not available.
+      # @param src [String] raw snappy block in ASCII-8BIT
+      # @return [String] decompressed bytes in ASCII-8BIT
+      # @raise [Error] if the block is corrupt or truncated
       def decompress_string(src)
         n = src.bytesize
         expected, pos = read_varint(src, n)
@@ -162,10 +236,15 @@ module Herringbone
 
       # @param input [String] bytes to compress
       # @return [String] raw snappy block in ASCII-8BIT
+      # @raise [Error] if the input is larger than MAX_UNCOMPRESSED
       def compress(input)
-        src = input.encoding == Encoding::BINARY ? input : input.b
+        src = (input.encoding == Encoding::BINARY) ? input : input.b
         n = src.bytesize
+        # Checked for libsnappy too: it would truncate the 32-bit length preamble without complaint
         raise Error, "input too large for snappy" if n > MAX_UNCOMPRESSED
+        if (lib = native)
+          return lib.deflate(src)
+        end
 
         out = String.new(capacity: 32 + n + n / 6, encoding: Encoding::BINARY)
         write_varint(out, n)
@@ -181,6 +260,11 @@ module Herringbone
         out
       end
 
+      # Reads the uncompressed-length preamble (a little-endian base-128 varint) at the start of +src+.
+      # @param src [String] raw snappy block
+      # @param n [Integer] byte size of +src+
+      # @return [Array(Integer, Integer)] the declared uncompressed length and the offset just past the varint
+      # @raise [Error] if the varint is truncated, longer than 5 bytes or exceeds MAX_UNCOMPRESSED
       def read_varint(src, n)
         value = 0
         shift = 0
@@ -198,6 +282,10 @@ module Herringbone
         [value, pos]
       end
 
+      # Appends +value+ as a little-endian base-128 varint (the length preamble).
+      # @param out [String] binary output buffer, appended to
+      # @param value [Integer] non-negative length to encode
+      # @return [String] +out+
       def write_varint(out, value)
         while value >= 0x80
           out << ((value & 0x7f) | 0x80)
@@ -210,6 +298,12 @@ module Herringbone
       # positions relative to `base`; matches never cross the block boundary.
       # The 4-byte little-endian word at every position of the block is unpacked up front
       # (in C, via String#unpack) so hashing and match checks are single Array lookups.
+      # @param src [String] whole input in ASCII-8BIT
+      # @param base [Integer] offset of the fragment in +src+
+      # @param len [Integer] fragment length, at most BLOCK_SIZE
+      # @param out [String] binary output buffer, appended to
+      # @param table [Array<Integer>] zeroed hash table of 1 << HASH_BITS fragment-relative positions
+      # @return [void]
       def compress_block(src, base, len, out, table)
         ip_end = base + len
         next_emit = base
@@ -280,12 +374,24 @@ module Herringbone
 
       # words[k][j] is the 4-byte little-endian value at base + 4 * j + k, so the word at
       # relative position i is words[i & 3][i >> 2]
+      # @param src [String] whole input in ASCII-8BIT
+      # @param base [Integer] offset of the fragment in +src+
+      # @param len [Integer] fragment length
+      # @return [Array<Array<Integer>>] four arrays of 32-bit words, one per byte phase
       def block_words(src, base, len)
         Array.new(4) { |k| src.byteslice(base + k, len - k).unpack("V*") }
       end
 
       # Like match_length, but compares 4 bytes at a time using the unpacked block words,
       # which avoids allocating substrings for the (common) short matches.
+      # Falls back to match_length once a match reaches 64 bytes.
+      # @param words [Array<Array<Integer>>] fragment words from block_words
+      # @param src [String] whole input in ASCII-8BIT
+      # @param base [Integer] offset of the fragment in +src+
+      # @param s1 [Integer] absolute offset of the earlier occurrence
+      # @param s2 [Integer] absolute offset of the current position (s1 < s2)
+      # @param limit [Integer] absolute offset not to read past (the fragment end)
+      # @return [Integer] number of equal bytes starting at s1 and s2
       def match_length_words(words, src, base, s1, s2, limit)
         start = s2
         r1 = s1 - base
@@ -307,6 +413,11 @@ module Herringbone
 
       # Number of equal bytes at s1 and s2 (s1 < s2), not reading past limit. Gallops
       # with byteslice comparisons (memcmp) to avoid per-byte loops on long matches.
+      # @param src [String] whole input in ASCII-8BIT
+      # @param s1 [Integer] absolute offset of the earlier occurrence
+      # @param s2 [Integer] absolute offset of the current position
+      # @param limit [Integer] absolute offset not to read past
+      # @return [Integer] number of equal bytes
       def match_length(src, s1, s2, limit)
         start = s2
         return 0 if s2 >= limit || src.getbyte(s1) != src.getbyte(s2)
@@ -330,6 +441,13 @@ module Herringbone
         s2 - start
       end
 
+      # Appends a literal element: the tag (with a 1-4 byte length extension for long literals)
+      # followed by the bytes themselves. Does nothing for an empty literal.
+      # @param out [String] binary output buffer, appended to
+      # @param src [String] whole input in ASCII-8BIT
+      # @param pos [Integer] offset of the literal bytes in +src+
+      # @param len [Integer] number of literal bytes
+      # @return [String, nil] +out+, or nil when +len+ is zero
       def emit_literal(out, src, pos, len)
         return if len == 0
         n = len - 1
@@ -348,6 +466,11 @@ module Herringbone
       end
 
       # Offsets are always < 64KB (matches stay within a block), so 4-byte offsets are never needed.
+      # Long matches are split into copies of at most 64 bytes, never leaving a remainder under 4.
+      # @param out [String] binary output buffer, appended to
+      # @param offset [Integer] backward distance to the match source, 1...65536
+      # @param len [Integer] match length, at least 4
+      # @return [String] +out+
       def emit_copy(out, offset, len)
         while len >= 68
           emit_copy_upto64(out, offset, 64)
@@ -360,6 +483,12 @@ module Herringbone
         emit_copy_upto64(out, offset, len)
       end
 
+      # Appends one copy element: the 2-byte form (1-byte offset) when len is 4..11 and offset < 2048,
+      # otherwise the 3-byte form with a 2-byte offset.
+      # @param out [String] binary output buffer, appended to
+      # @param offset [Integer] backward distance to the match source, 1...65536
+      # @param len [Integer] copy length, 4..64
+      # @return [String] +out+
       def emit_copy_upto64(out, offset, len)
         if len < 12 && offset < 2048
           out << (1 | ((len - 4) << 2) | ((offset >> 8) << 5)) << (offset & 0xff)
@@ -368,7 +497,7 @@ module Herringbone
         end
       end
 
-      private_class_method :decompress_io_buffer, :decompress_string, :read_varint, :write_varint, :compress_block, :block_words, :match_length_words,
+      private_class_method :native, :native_library, :decompress_io_buffer, :decompress_string, :read_varint, :write_varint, :compress_block, :block_words, :match_length_words,
         :match_length, :emit_literal, :emit_copy, :emit_copy_upto64
     end
   end

data/lib/herringbone/compression.rb

@@ -6,8 +6,12 @@ require "stringio"
 module Herringbone
   # Raised when a file uses (or a writer asks for) a codec whose library is not installed
   class MissingCodecError < UnsupportedError
+    # @return [String] codec name (+"ZSTD"+) and name of the gem providing it (+"zstd-ruby"+)
     attr_reader :codec, :gem_name
 
+    # @param codec [String] codec name, as shown in the message
+    # @param gem_name [String] gem to add to the Gemfile
+    # @param load_error [LoadError] the error from requiring the gem, whose message is included
     def initialize(codec, gem_name, load_error)
       @codec = codec
       @gem_name = gem_name
@@ -19,6 +23,7 @@ module Herringbone
   # Dispatches page (de)compression by Parquet codec id. Snappy and LZ4 are pure Ruby and GZIP
   # uses zlib, so those always work. ZSTD and Brotli come from optional gems (zstd-ruby, brotli),
   # which are required on first use; if they are missing, MissingCodecError says what to add.
+  # (Snappy also uses the optional snappy gem when it is installed, see Codecs::Snappy.)
   module Compression
     module_function
 
@@ -32,6 +37,11 @@ module Herringbone
     @library_mutex = Mutex.new
 
     # The library module for a codec backed by an optional gem, requiring it on first use
+    #
+    # @param codec [Integer] a codec id that is a key of LIBRARIES
+    # @return [Module] the gem's module (+Zstd+ or +Brotli+)
+    # @raise [MissingCodecError] when the gem cannot be loaded
+    # @raise [KeyError] for a codec id not in LIBRARIES
     def library(codec)
       @libraries.fetch(codec) do
         @library_mutex.synchronize do
@@ -48,11 +58,22 @@ module Herringbone
       end
     end
 
+    # Requires a codec gem; a separate method so tests can stub it to simulate a missing gem
+    #
+    # @param path [String] require path of the gem
+    # @return [Boolean] whether the library was newly loaded
+    # @raise [LoadError] when the gem is not installed
     def require_library(path)
       require path
     end
 
     # Raises MissingCodecError (or UnsupportedError) unless +codec+ can be used
+    #
+    # @param codec [Integer, Symbol, String] codec id or name (see NAMES)
+    # @return [Module, nil] the gem's module for a gem-backed codec, nil for a built-in one
+    # @raise [MissingCodecError] when the codec's gem cannot be loaded
+    # @raise [UnsupportedError] for a codec herringbone does not implement (LZO)
+    # @raise [ArgumentError] for an unknown codec name
     def ensure_available!(codec)
       codec = codec_id(codec)
       return library(codec) if LIBRARIES.key?(codec)
@@ -60,6 +81,7 @@ module Herringbone
       raise UnsupportedError, "#{Format::Codec::NAMES[codec] || codec} compression is not supported"
     end
 
+    # Codec ids that work without optional gems
     SUPPORTED = [
       Format::Codec::UNCOMPRESSED, Format::Codec::SNAPPY, Format::Codec::GZIP,
       Format::Codec::LZ4_RAW, Format::Codec::LZ4
@@ -71,8 +93,14 @@ module Herringbone
       Format::Codec::LZ4_RAW => :lz4, Format::Codec::LZ4 => :lz4_hadoop, Format::Codec::ZSTD => :zstd,
       Format::Codec::BROTLI => :brotli, Format::Codec::LZO => :lzo
     }.freeze
+    # Codec name => codec id, the inverse of NAMES
     CODECS_BY_NAME = NAMES.invert.freeze
 
+    # Codec id for a codec name; Integers are taken to be ids already and returned unchecked
+    #
+    # @param name [Integer, Symbol, String] codec id, or a name from NAMES (case-insensitive)
+    # @return [Integer] the Format::Codec id
+    # @raise [ArgumentError] for an unknown name
     def codec_id(name)
       return name if name.is_a?(Integer)
       CODECS_BY_NAME.fetch(name.to_s.downcase.to_sym) do
@@ -80,6 +108,15 @@ module Herringbone
       end
     end
 
+    # Decompresses a page body, checking the result against the size the page header declares
+    #
+    # @param codec [Integer] Format::Codec id from the column chunk metadata
+    # @param data [String] compressed bytes
+    # @param uncompressed_size [Integer] expected decompressed size in bytes
+    # @return [String] decompressed bytes (binary)
+    # @raise [UnsupportedError] for a codec herringbone does not implement
+    # @raise [MissingCodecError] when the codec's gem cannot be loaded
+    # @raise [FormatError] when the decompressed size does not match +uncompressed_size+
     def decompress(codec, data, uncompressed_size)
       return "".b if uncompressed_size.zero? && data.empty?
       out = case codec
@@ -100,6 +137,13 @@ module Herringbone
       out
     end
 
+    # Compresses a page body
+    #
+    # @param codec [Integer] Format::Codec id
+    # @param data [String] bytes to compress
+    # @return [String] compressed bytes (binary)
+    # @raise [UnsupportedError] for a codec herringbone does not implement
+    # @raise [MissingCodecError] when the codec's gem cannot be loaded
     def compress(codec, data)
       case codec
       when Format::Codec::UNCOMPRESSED then data
@@ -115,6 +159,10 @@ module Herringbone
     end
 
     # Handles files whose gzip data consists of several concatenated members
+    #
+    # @param data [String] gzip data, one or more members
+    # @return [String] the members' decompressed bytes concatenated (binary)
+    # @raise [Zlib::GzipFile::Error] on corrupt gzip data
     def gunzip(data)
       io = StringIO.new(data)
       out = String.new(encoding: Encoding::BINARY)