Transforms: add docs

Author: asppsa

lib/moneta/transform.rb

@@ -11,9 +11,9 @@ class Transform
     autoload :Serializer, "moneta/transform/serializer"
 
     # This helper can be used in subclasses to implement {#encode} and {#decode} by delegating to some other object.  If
-    # the object delegated to responds to encode (and optionally decode) or dump (and optionally load), these will be
-    # detected automatically.  Otherwise, a second argument can be supplied giving the names of the methods to use as a
-    # pair of symbols (encode then optionally decode).
+    # the object delegated to responds to +encode+ (and optionally +decode+) or +dump+ (and optionally +load+), these
+    # will be detected automatically.  Otherwise, a second argument can be supplied giving the names of the methods to
+    # use as a pair of symbols (+encode+ then optionally +decode+).
     #
     # @example Delegate to stdlib JSON library
     #   require 'json'
@@ -33,6 +33,17 @@ class Transform
     #
     # @param object [Module] The object to delegate to
     # @param methods [<Symbol,Symbol>] The methods on +object+ to delegate to
+    #
+    # @!macro [attach] transform_delegate_to
+    #   @!method encode(value)
+    #     Delegates to $1
+    #     @param value [Object]
+    #     @return [Object]
+    #
+    #   @!method decode(value)
+    #     Delegates to $1
+    #     @param value [Object]
+    #     @return [Object]
     def self.delegate_to(object, methods = nil)
       extend Forwardable
 
@@ -56,10 +67,19 @@ def self.delegate_to(object, methods = nil)
 
     # Transforms can be initialized with arbitrary keyword args.  The default
     # initializer does nothing, just swallows the arguments it receives.
-    def initialize(**_)
-    end
+    def initialize(**_) end
+
+    # @!method encode(value)
+    #   @abstract All Subclasses should implement this method
+    #   @param value [Object] the thing to encode
+    #   @return [Object]
+    #
+    # @!method decode(value)
+    #   @abstract Subclasses where it is possible to decode again should implement this method
+    #   @param value [Object] the thing to decode
+    #   @return [Object]
 
-    # Returns true if the Tranform has a {#decode} method.  Some transforms
+    # Returns true if the transform has a {#decode} method.  Some transforms
     # (e.g. MD5) are one-way.
     def decodable?
       respond_to? :decode

lib/moneta/transform/serializer.rb

@@ -39,6 +39,17 @@ class Serializer < Transform
       #
       # @param object [Module] The object to delegate to
       # @param methods [<Symbol,Symbol>] The methods on +object+ to delegate to
+      #
+      # @!macro [attach] transform_serializer_delegate_to
+      #   @!method serialize(value)
+      #     Delegates to $1
+      #     @param value [Object]
+      #     @return [Object]
+      #
+      #   @!method deserialize(value)
+      #     Delegates to $1
+      #     @param value [Object]
+      #     @return [Object]
       def self.delegate_to(object, methods = nil)
         extend Forwardable
 
@@ -74,7 +85,7 @@ def initialize(serialize_unless_string: false, **_)
       # string.
       #
       # @param value [Object] object to encode
-      # @return [String] The serialized string
+      # @return [Object] The serialized object (usually string)
       def encode(value)
         if @serialize_unless_string && String === value
           value
@@ -85,7 +96,7 @@ def encode(value)
 
       # Calls {#deserialize} if implemented and if +serialize_unless_string+ was disabled
       #
-      # @param value [String] object to decode
+      # @param value [Object] object to decode
       # @return [Object] the decoded object
       # @raise [NotImplementedError] if this serializer cannot do deserialization
       def decode(value)
@@ -99,6 +110,20 @@ def decode(value)
       def decodable?
         !@serialize_unless_string && respond_to?(:deserialize)
       end
+
+      # @!method serialize(value)
+      #   This method will be called by {#encode} except when the value being encoded is a string, and the object is in
+      #   +serialize_unless_string+ mode.
+      #   @abstract All Subclasses should implement this method
+      #   @param value [Object] the thing to encode
+      #   @return [Object]
+      #
+      # @!method decode(value)
+      #   This method will be called by {#decode} except when in +serialize_unless_string+ mode (in which case
+      #   deserialization is disabled).
+      #   @abstract Subclasses where it is possible to deserialize again should implement this method
+      #   @param value [Object] the thing to decode
+      #   @return [Object]
     end
   end
 end

lib/moneta/transforms.rb

@@ -1,4 +1,5 @@
 module Moneta
+  # This module is used to namespace Moneta's built-in transform classes, as used by {Moneta::Transformer}.
   module Transforms
     TRANSFORMS = %i[
       BEncode
@@ -45,13 +46,18 @@ module Transforms
       autoload transform, "moneta/transforms/#{transform.to_s.downcase}"
     end
 
+    # Used by {Moneta::Transformer} to initialise instances of {Moneta::Transform} to do key/value encoding and
+    # decoding.
+    #
+    # @param name [String,Symbol] The name of the transform
+    # @return [Module] A class that implements the {Moneta::Transform} interface when initialized
     def self.module_for(name)
       transform_sym =
         case name
         when :msgpack
           :MessagePack
         else
-          name_str = name.to_s.gsub('_', '')
+          name_str = name.to_s.gsub("_", "")
           TRANSFORMS.find do |transform|
             transform == name ||
               transform.to_s.downcase == name_str

lib/moneta/transforms/base64.rb

@@ -2,6 +2,7 @@
 
 module Moneta
   module Transforms
+    # Encodes text as Base64 using the stdlib +base64+ library
     class Base64 < Transform
       def initialize(url_safe: false, strict: false, **options)
         super

lib/moneta/transforms/bencode.rb

@@ -1,12 +1,15 @@
-require 'bencode'
+require "bencode"
 
 module Moneta
   module Transforms
+    # Serializes objects using the {https://github.com/dasch/ruby-bencode bencode gem}
     class BEncode < Transform::Serializer
+      # (see Transform::Serializer#serialize)
       def serialize(value)
         ::BEncode.dump(value)
       end
 
+      # (see Transform::Serializer#deserialize)
       def deserialize(value)
         # BEncode needs a mutable string
         ::BEncode.load(value.dup).tap do |deserialized_value|

lib/moneta/transforms/bert.rb

@@ -1,7 +1,8 @@
-require 'bert'
+require "bert"
 
 module Moneta
   module Transforms
+    # Encodes text using the {https://rubygems.org/gems/bert bert gem}.
     class BERT < Transform::Serializer
       delegate_to ::BERT
     end

lib/moneta/transforms/bson.rb

@@ -1,14 +1,23 @@
-require 'bson'
+require "bson"
 
 module Moneta
   module Transforms
+    # Serializes objects to binary strings using the {https://rubygems.org/gems/bson bson gem}
     class BSON < Transforms::Serializer
+      # Serialize to BSON
+      #
+      # @param value [Object]
+      # @return [String]
       def serialize(value)
-        ::BSON::Document['v' => value].to_bson.to_s
+        ::BSON::Document["v" => value].to_bson.to_s
       end
 
+      # Deserialize from BSON
+      #
+      # @param value [String]
+      # @return [Object]
       def deserialize(value)
-        ::BSON::Document.from_bson(::BSON::ByteBuffer.new(value))['v']
+        ::BSON::Document.from_bson(::BSON::ByteBuffer.new(value))["v"]
       end
     end
   end

lib/moneta/transforms/bzip2.rb

@@ -1,8 +1,14 @@
-require 'rbzip2'
+require "rbzip2"
+require "stringio"
 
 module Moneta
   module Transforms
+    # Compresses strings using the {https://rubygems.org/gems/rbzip2 rbzip2 gem}
     class Bzip2 < Transform
+      # Compresses using BZip2
+      #
+      # @param value [String]
+      # @return [String]
       def encode(value)
         io = ::StringIO.new
         bz = ::RBzip2.default_adapter::Compressor.new(io)
@@ -11,6 +17,18 @@ def encode(value)
         io.string
       end
 
+      # Returns true if the string starts with the right magic number ("BZh")
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def encoded?(value)
+        String === value && value.byteslice(0, 3) == "BZh"
+      end
+
+      # Decompresses BZip2-compressed data
+      #
+      # @param value [String]
+      # @return [String]
       def decode(value)
         ::RBzip2.default_adapter::Decompressor.new(::StringIO.new(value)).read
       end

lib/moneta/transforms/city128.rb

@@ -1,8 +1,13 @@
-require 'cityhash'
+require "cityhash"
 
 module Moneta
   module Transforms
+    # Hashes strings using the {https://rubygems.org/gems/cityhash cityhash gem} - 128 bit version
     class City128 < Transform
+      # Hashes using the +CityHash128+ algorithm
+      #
+      # @param [String]
+      # @return [String]
       def encode(value)
         ::CityHash.hash128(value).to_s(16)
       end

lib/moneta/transforms/city32.rb

@@ -1,8 +1,13 @@
-require 'cityhash'
+require "cityhash"
 
 module Moneta
   module Transforms
+    # Hashes strings using the {https://rubygems.org/gems/cityhash cityhash gem} - 32 bit version
     class City32 < Transform
+      # Hashes using the +CityHash32+ algorithm
+      #
+      # @param [String]
+      # @return [String]
       def encode(value)
         ::CityHash.hash32(value).to_s(16)
       end