RubyGems - maxcube-client - Versions diffs - 0.4.1 → 0.5.0 - Mend

maxcube-client 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (109) hide show

checksums.yaml +4 -4
data/.gitignore +6 -0
data/.rubocop.yml +0 -3
data/.yardopts +1 -0
data/README.md +17 -2
data/bin/maxcube-client +2 -27
data/doc/MaxCube.html +502 -0
data/doc/MaxCube/Messages.html +1927 -0
data/doc/MaxCube/Messages/Handler.html +2912 -0
data/doc/MaxCube/Messages/InvalidMessage.html +140 -0
data/doc/MaxCube/Messages/InvalidMessageBody.html +264 -0
data/doc/MaxCube/Messages/InvalidMessageFormat.html +247 -0
data/doc/MaxCube/Messages/InvalidMessageLength.html +247 -0
data/doc/MaxCube/Messages/InvalidMessageType.html +263 -0
data/doc/MaxCube/Messages/Parser.html +520 -0
data/doc/MaxCube/Messages/Serializer.html +701 -0
data/doc/MaxCube/Messages/TCP.html +172 -0
data/doc/MaxCube/Messages/TCP/Handler.html +1396 -0
data/doc/MaxCube/Messages/TCP/Parser.html +462 -0
data/doc/MaxCube/Messages/TCP/Parser/MessageA.html +186 -0
data/doc/MaxCube/Messages/TCP/Parser/MessageC.html +1077 -0
data/doc/MaxCube/Messages/TCP/Parser/MessageF.html +206 -0
data/doc/MaxCube/Messages/TCP/Parser/MessageH.html +338 -0
data/doc/MaxCube/Messages/TCP/Parser/MessageL.html +535 -0
data/doc/MaxCube/Messages/TCP/Parser/MessageM.html +510 -0
data/doc/MaxCube/Messages/TCP/Parser/MessageN.html +226 -0
data/doc/MaxCube/Messages/TCP/Parser/MessageS.html +225 -0
data/doc/MaxCube/Messages/TCP/Serializer.html +460 -0
data/doc/MaxCube/Messages/TCP/Serializer/MessageA.html +186 -0
data/doc/MaxCube/Messages/TCP/Serializer/MessageC.html +185 -0
data/doc/MaxCube/Messages/TCP/Serializer/MessageF.html +206 -0
data/doc/MaxCube/Messages/TCP/Serializer/MessageL.html +185 -0
data/doc/MaxCube/Messages/TCP/Serializer/MessageM.html +428 -0
data/doc/MaxCube/Messages/TCP/Serializer/MessageN.html +209 -0
data/doc/MaxCube/Messages/TCP/Serializer/MessageQ.html +185 -0
data/doc/MaxCube/Messages/TCP/Serializer/MessageS.html +1168 -0
data/doc/MaxCube/Messages/TCP/Serializer/MessageT.html +240 -0
data/doc/MaxCube/Messages/TCP/Serializer/MessageU.html +206 -0
data/doc/MaxCube/Messages/TCP/Serializer/MessageZ.html +252 -0
data/doc/MaxCube/Messages/UDP.html +164 -0
data/doc/MaxCube/Messages/UDP/Handler.html +832 -0
data/doc/MaxCube/Messages/UDP/Parser.html +609 -0
data/doc/MaxCube/Messages/UDP/Parser/MessageH.html +218 -0
data/doc/MaxCube/Messages/UDP/Parser/MessageI.html +215 -0
data/doc/MaxCube/Messages/UDP/Parser/MessageN.html +226 -0
data/doc/MaxCube/Messages/UDP/Serializer.html +484 -0
data/doc/MaxCube/Network.html +167 -0
data/doc/MaxCube/Network/TCP.html +150 -0
data/doc/MaxCube/Network/TCP/Client.html +1930 -0
data/doc/MaxCube/Network/TCP/Client/Commands.html +2457 -0
data/doc/MaxCube/Network/TCP/SampleServer.html +910 -0
data/doc/MaxCube/Network/UDP.html +150 -0
data/doc/MaxCube/Network/UDP/Client.html +518 -0
data/doc/MaxCube/Network/UDP/SampleSocket.html +628 -0
data/doc/MaxCube/Runner.html +355 -0
data/doc/_index.html +518 -0
data/doc/class_list.html +51 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +58 -0
data/doc/css/style.css +499 -0
data/doc/file.README.html +140 -0
data/doc/file_list.html +56 -0
data/doc/frames.html +17 -0
data/doc/index.html +140 -0
data/doc/js/app.js +248 -0
data/doc/js/full_list.js +216 -0
data/doc/js/jquery.js +4 -0
data/doc/method_list.html +1699 -0
data/doc/top-level-namespace.html +110 -0
data/lib/maxcube.rb +11 -0
data/lib/maxcube/messages.rb +85 -8
data/lib/maxcube/messages/handler.rb +138 -4
data/lib/maxcube/messages/parser.rb +33 -2
data/lib/maxcube/messages/serializer.rb +64 -16
data/lib/maxcube/messages/tcp.rb +11 -7
data/lib/maxcube/messages/tcp/handler.rb +50 -2
data/lib/maxcube/messages/tcp/parser.rb +18 -17
data/lib/maxcube/messages/tcp/serializer.rb +20 -21
data/lib/maxcube/messages/tcp/type/a.rb +6 -6
data/lib/maxcube/messages/tcp/type/c.rb +5 -3
data/lib/maxcube/messages/tcp/type/f.rb +5 -3
data/lib/maxcube/messages/tcp/type/h.rb +3 -2
data/lib/maxcube/messages/tcp/type/l.rb +8 -7
data/lib/maxcube/messages/tcp/type/m.rb +11 -7
data/lib/maxcube/messages/tcp/type/n.rb +5 -3
data/lib/maxcube/messages/tcp/type/q.rb +2 -2
data/lib/maxcube/messages/tcp/type/s.rb +5 -2
data/lib/maxcube/messages/tcp/type/t.rb +5 -4
data/lib/maxcube/messages/tcp/type/u.rb +2 -1
data/lib/maxcube/messages/tcp/type/z.rb +4 -2
data/lib/maxcube/messages/udp.rb +7 -0
data/lib/maxcube/messages/udp/handler.rb +28 -0
data/lib/maxcube/messages/udp/parser.rb +23 -6
data/lib/maxcube/messages/udp/serializer.rb +17 -1
data/lib/maxcube/messages/udp/type/h.rb +2 -0
data/lib/maxcube/messages/udp/type/i.rb +3 -0
data/lib/maxcube/messages/udp/type/n.rb +3 -0
data/lib/maxcube/network.rb +5 -1
data/lib/maxcube/network/tcp.rb +3 -0
data/lib/maxcube/network/tcp/client.rb +117 -3
data/lib/maxcube/network/tcp/client/commands.rb +306 -239
data/lib/maxcube/network/tcp/sample_server.rb +1 -0
data/lib/maxcube/network/udp.rb +3 -0
data/lib/maxcube/network/udp/client.rb +2 -0
data/lib/maxcube/network/udp/sample_socket.rb +1 -0
data/lib/maxcube/runner.rb +45 -0
data/lib/maxcube/version.rb +2 -1
data/maxcube-client.gemspec +2 -0
metadata +84 -3

data/doc/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.9.12
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+<script type="text/javascript" charset="utf-8">
+  pathId = "";
+  relpath = '';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+</div>
+        <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+</div>
+        <div class="clear"></div>
+      </div>
+      <div id="content"><h1>Top Level Namespace
+</h1>
+<div class="box_info">
+</div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="MaxCube.html" title="MaxCube (module)">MaxCube</a></span>
+</p>
+</div>
+      <div id="footer">
+  Generated on Fri Feb 16 13:44:01 2018 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.12 (ruby-2.5.0).
+</div>
+    </div>
+  </body>
+</html>

data/lib/maxcube.rb CHANGED Viewed

@@ -1,4 +1,5 @@
 require 'date'
+require 'time'
 require 'pathname'
 require 'ipaddr'
@@ -6,19 +7,29 @@ require 'pp'
 require 'maxcube/version'
+# Root project module that contains only project-related utilities
 module MaxCube
+  # Gets path to project root directory
+  # @return [String] path to project root directory
   def self.root_dir
     File.dirname __dir__
   end
+  # Gets path to +bin/+ project directory with executables
+  # @return [String] path to +bin/+ project directory
   def self.bin_dir
     File.join(root_dir, 'bin')
   end
+  # Gets path to +lib/+ project directory with Ruby source files
+  # @return [String] path to +lib/+ project directory
   def self.lib_dir
     File.join(root_dir, 'lib')
   end
+  # Gets path to +data/+ project directory
+  # with input/output data for clients and servers
+  # @return [String] path to +data/+ project directory
   def self.data_dir
     File.join(root_dir, 'data')
   end

data/lib/maxcube/messages.rb CHANGED Viewed

@@ -1,39 +1,58 @@
 require 'maxcube'
 module MaxCube
+  # Encapsulates methods related to Cube messages,
+  # i.e. parsing and serializing of TCP/UDP messages.
+  # It does not provide any network features
+  # (this is responsibility of {Network}.
   module Messages
+    # Device modes that determines geating scheduling.
     DEVICE_MODE = %i[auto manual vacation boost].freeze
+    # Device types identified in Cube protocol.
     DEVICE_TYPE = %i[cube
                      radiator_thermostat radiator_thermostat_plus
                      wall_thermostat
                      shutter_contact eco_switch].freeze
+    # Names of days of week in order Cube protocol uses.
     DAYS_OF_WEEK = %w[Saturday Sunday Monday
                       Tuesday Wednesday Thursday Friday].freeze
-    PACK_FORMAT = %w[x C n N N].freeze
+    # Base exception class
+    # that denotes an error during message parsing/serializing.
     class InvalidMessage < RuntimeError; end
+    # Exception class that denotes that message is too short/long.
     class InvalidMessageLength < InvalidMessage
+      # @param info contains context information to occured error.
       def initialize(info = 'invalid message length')
         super
       end
     end
+    # Exception class that denotes unrecognized message type.
     class InvalidMessageType < InvalidMessage
+      # @param msg_type type of message that is being parsed/serialized.
+      # @param info contains context information to occured error.
       def initialize(msg_type, info = 'invalid message type')
         super("#{info}: #{msg_type}")
       end
     end
+    # Exception class that denotes invalid syntax format of message.
     class InvalidMessageFormat < InvalidMessage
+      # @param info contains context information to occured error.
       def initialize(info = 'invalid format')
         super
       end
     end
+    # Exception class that denotes that an error occured
+    # while parsing/serializing message body,
+    # which is specific to message type.
     class InvalidMessageBody < InvalidMessage
+      # @param msg_type type of message that is being parsed/serialized.
+      # @param info contains context information to occured error.
       def initialize(msg_type, info = 'invalid format')
         super("message type #{msg_type}: #{info}")
       end
@@ -41,6 +60,17 @@ module MaxCube
     private
+    # Applies a block to given arguments
+    # in order to perform conversion to certain type.
+    # If conversion fails, {InvalidMessageBody} is raised.
+    # Thus, this method can be used also for type checking purposes only.
+    # @param type [#to_s] name of the type to convert to.
+    # @param info [#to_s] context information to pass to raised error.
+    # @param args [Array] arguments to be converted into the same type.
+    # @yield a rule to provide
+    #   certain type check and conversion of arguments.
+    # @return [Array] converted elements.
+    # @raise [InvalidMessageBody] if conversion fails.
     def conv_args(type, info, *args, &block)
       info = info.to_s.tr('_', ' ')
       args.map(&block)
@@ -50,25 +80,44 @@ module MaxCube
              "invalid #{type} format of arguments #{args} (#{info})")
     end
-    # Convert string of characters (not binary data!) to hex number
-    # For binary data use #String.unpack
+    # Uses {#conv_args} to convert numbers
+    # or string of characters (not binary data!)
+    # to integers in given base (radix).
+    # For binary data use {Parser#read}.
+    # @param base [Integer] integers base (radix), 0 means auto-recognition.
+    # @param args [Array<#Integer>] arguments to convert to integers.
+    # @return [Array<Integer>] converted elements.
     def to_ints(base, info, *args)
       base_str = base.zero? ? '' : "(#{base})"
       conv_args("integer#{base_str}", info, *args) { |x| Integer(x, base) }
     end
+    # Uses {#to_ints}, but operates with single argument.
+    # @param arg [#Integer] argument to convert to integer.
+    # @return [Integer] converted element.
     def to_int(base, info, arg)
       to_ints(base, info, arg).first
     end
+    # Uses {#conv_args} to convert numbers
+    # or string of characters (not binary data!) to floats.
+    # @param args [Array<#Float>] arguments to convert to floats.
+    # @return [Array<Float>] converted elements.
     def to_floats(info, *args)
       conv_args('float', info, *args) { |x| Float(x) }
     end
+    # Uses {#to_floats}, but operates with single argument.
+    # @param arg [#Float] argument to convert to float.
+    # @return [Float] converted element.
     def to_float(info, arg)
       to_floats(info, arg).first
     end
+    # Uses {#conv_args} to convert objects to bools.
+    # @param args [Array] arguments to convert to bools.
+    # @return [Array<Boolean>] converted elements
+    #   to +TrueClass+ or +FalseClass+.
     def to_bools(info, *args)
       conv_args('boolean', info, *args) do |arg|
         if arg == !!arg
@@ -83,26 +132,47 @@ module MaxCube
       end
     end
+    # Uses {#to_bools}, but operates with single argument.
+    # @param arg argument to convert to bool.
+    # @return [Boolean] converted element
+    #   to +TrueClass+ or +FalseClass+.
     def to_bool(info, arg)
       to_bools(info, arg).first
     end
+    # Uses {#conv_args} to convert objects to +Time+.
+    # @param args [Array] arguments to convert to +Time+.
+    # @return [Array<Time>] converted elements.
     def to_datetimes(info, *args)
       conv_args('datetime', info, *args) do |arg|
-        if arg.is_a?(DateTime)
+        if arg.is_a?(Time)
           arg
-        elsif arg.respond_to?('to_datetime')
-          arg.to_datetime
+        elsif arg.is_a?(String)
+          Time.parse(arg)
+        elsif arg.respond_to?('to_time')
+          arg.to_time
+        elsif arg.respond_to?('to_date')
+          arg.to_date.to_time
         else
-          DateTime.parse(arg)
+          raise ArgumentError
         end
       end
     end
+    # Uses {#to_datetime}, but operates with single argument.
+    # @param arg argument to convert to +Time+.
+    # @return [Time] converted element.
     def to_datetime(info, arg)
       to_datetimes(info, arg).first
     end
+    # Helper method that checks presence of index in array
+    # (if not, exception is raised).
+    # @param ary [#[]] input container (usually constant).
+    # @param id index of element in container.
+    # @param info [#to_s] context information to pass to raised error.
+    # @return element of container if found.
+    # @raise [InvalidMessageBody] if element not found.
     def ary_elem(ary, id, info)
       elem = ary[id]
       return elem if elem
@@ -110,6 +180,7 @@ module MaxCube
         .new(@msg_type, "unrecognized #{info} id: #{id}")
     end
+    # Reverse method to {#ary_elem}.
     def ary_elem_id(ary, elem, info)
       id = ary.index(elem)
       return id if id
@@ -117,26 +188,32 @@ module MaxCube
         .new(@msg_type, "unrecognized #{info}: #{elem}")
     end
+    # Uses {#ary_elem} with {DEVICE_TYPE}
     def device_type(device_type_id)
       ary_elem(DEVICE_TYPE, device_type_id, 'device type')
     end
+    # Uses {#ary_elem_id} with {DEVICE_TYPE}
     def device_type_id(device_type)
       ary_elem_id(DEVICE_TYPE, device_type.to_sym, 'device type')
     end
+    # Uses {#ary_elem} with {DEVICE_MODE}
     def device_mode(device_mode_id)
       ary_elem(DEVICE_MODE, device_mode_id, 'device mode')
     end
+    # Uses {#ary_elem_id} with {DEVICE_MODE}
     def device_mode_id(device_mode)
       ary_elem_id(DEVICE_MODE, device_mode.to_sym, 'device mode')
     end
+    # Uses {#ary_elem} with {DAYS_OF_WEEK}
     def day_of_week(day_id)
       ary_elem(DAYS_OF_WEEK, day_id, 'day of week')
     end
+    # Uses {#ary_elem_id} with {DAYS_OF_WEEK}
     def day_of_week_id(day)
       if day.respond_to?('to_i') && day.to_i.between?(1, 7)
         return (day.to_i + 1) % 7

data/lib/maxcube/messages/handler.rb CHANGED Viewed

@@ -5,74 +5,147 @@ require 'maxcube/messages'
 module MaxCube
   module Messages
+    # This module provides methods that handles with messages
+    # regardless whether it is for parse or serialize purposes.
+    # It mostly contains methods that validates (returns Boolean)
+    # or checks (raises exception on failure) some part of message.
     module Handler
       include Messages
+      # Format characters to String#unpack and Array#pack,
+      # for purposes to convert binary string to integer.
+      # Elements are sorted by integer size in bytes.
+      PACK_FORMAT = %w[x C n N N].freeze
+      # Checks whether raw data string is +String+.
+      # @param raw_data input raw data string.
+      # @return [Boolean] +true+ if argument is +String+, +false+ otherwise.
       def valid_data_type(raw_data)
         raw_data.is_a?(String)
       end
+      # Checks whether {#valid_data_type} is +true+.
+      # If not, exception is raised.
+      # @return [String] input raw data string.
+      # @raise [TypeError] if argument is _not_ valid.
       def check_data_type(raw_data)
         raise TypeError unless valid_data_type(raw_data)
         raw_data
       end
+      # Validates whether message type character is valid.
+      # Calls {#maybe_check_valid_msg_type}.
+      # @param msg_type [String] input message type character.
+      # @return [Boolean] +true+ if argument is valid message type.
       def valid_msg_type(msg_type)
         maybe_check_valid_msg_type(msg_type, false)
       end
+      # Checks whether message type character is valid.
+      # Calls {#maybe_check_valid_msg_type}.
+      # If argument is valid, it assigns the message type to internal variable.
+      # @param msg_type [String] input message type character.
+      # @return [String] message type character assigned to internal variable.
+      # @raise [InvalidMessageType] if validation fails.
       def check_msg_type(msg_type)
         maybe_check_valid_msg_type(msg_type, true)
         @msg_type
       end
+      # Validates whether message type character of message is valid.
+      # Calls {#valid_msg_type} and #msg_msg_type
+      # (this method depends on conrete end-class).
+      # @param msg [String] input message.
       def valid_msg_msg_type(msg)
         valid_msg_type(msg_msg_type(msg))
       end
+      # Checks whether message type character of message is valid.
+      # Calls {#check_msg_type} and #msg_msg_type
+      # (this method depends on conrete end-class).
+      # If argument is valid, it assigns the message type to internal variable.
+      # @param msg [String] input message.
       def check_msg_msg_type(msg)
         check_msg_type(msg_msg_type(msg))
       end
+      # Validates whether whole message is valid
+      # from general point of view, independently of parser/sserializer.
+      # Currently, it just calls {#valid_msg_msg_type}.
+      # @param msg [String] input message.
       def valid_msg(msg)
         valid_msg_msg_type(msg)
       end
+      # As {#valid_msg}, but raises exception if message is invalid.
+      # Currently, it just calls {#check_msg_msg_type}.
+      # @param msg [String] input message.
       def check_msg(msg)
         check_msg_msg_type(msg)
       end
+      # Validates whether message type character in hash is valid.
+      # Calls {#valid_msg_type}.
+      # @param hash [Hash] input hash.
       def valid_hash_msg_type(hash)
         valid_msg_type(hash[:type])
       end
+      # Checks whether message type character in hash is valid.
+      # Calls {#check_msg_type}.
+      # If argument is valid, it assigns the message type to internal variable.
+      # @param hash [Hash] input hash.
       def check_hash_msg_type(hash)
-        msg_type = hash[:type]
-        check_msg_type(msg_type)
-        msg_type
+        check_msg_type(hash[:type])
       end
+      # Returns hash keys that are related to given message type.
+      # Each hash with a message type should contain these keys.
+      # Calls {#msg_type_which_hash_keys}.
+      # @param msg_type [String] message type that is being parsed/serialized.
       def msg_type_hash_keys(msg_type)
         msg_type_which_hash_keys(msg_type, false)
       end
+      # Returns optional hash keys that are related to given message type.
+      # Calls {#msg_type_which_hash_keys}.
+      # @param msg_type [String] message type that is being parsed/serialized.
       def msg_type_hash_opt_keys(msg_type)
         msg_type_which_hash_keys(msg_type, true)
       end
+      # Validates if given hash contain valid keys,
+      # depending on its message type
+      # (according to {#msg_type_which_hash_keys}).
+      # Calls {#maybe_check_valid_hash_keys}.
+      # @param hash [Hash] input hash.
       def valid_hash_keys(hash)
         maybe_check_valid_hash_keys(hash, false)
       end
+      # As {#valid_hash_keys}, but raises exception if hash is _not_ valid.
+      # Calls {#maybe_check_valid_hash_keys}.
+      # @param hash [Hash] input hash.
+      # @return [Hash] input hash.
       def check_hash_keys(hash)
         maybe_check_valid_hash_keys(hash, true)
         hash
       end
+      # Validates if values of given hash satisfies basic conditions
+      # for all hashes being used with messages.
+      # @param hash [Hash] input hash.
+      # @return [Boolean] +true+ if hash values are valid
+      #   (from general point of view).
       def valid_hash_values(hash)
         hash.none? { |_, v| v.nil? }
       end
+      # As {#valid_hash_values}, but raises exception
+      # if hash values are _not_ valid.
+      # @param hash [Hash] input hash.
+      # @return [Hash] input hash.
+      # @raise [InvalidMessageBody] if hash values are _not_ valid.
       def check_hash_values(hash)
         return hash if valid_hash_values(hash)
         hash = hash.dup
@@ -81,12 +154,24 @@ module MaxCube
           .new(@msg_type, "invalid hash values: #{hash}")
       end
+      # Validates if given hash satisfies basic conditions
+      # for all hashes being used with messages.
+      # Calls {#valid_hash_msg_type},
+      # {#valid_hash_keys} and {#valid_hash_values}.
+      # @param hash [Hash] input hash.
+      # @return [Boolean] +true+ if hash is valid
+      #   (from general point of view).
       def valid_hash(hash)
         valid_hash_msg_type(hash) &&
           valid_hash_keys(hash) &&
           valid_hash_values(hash)
       end
+      # As {#valid_hash}, but raises exception if hash is _not_ valid.
+      # Calls {#check_hash_msg_type},
+      # {#check_hash_keys} and {#check_hash_values}.
+      # @param hash [Hash] input hash.
+      # @return [Hash] input hash.
       def check_hash(hash)
         check_hash_msg_type(hash)
         check_hash_keys(hash)
@@ -96,10 +181,18 @@ module MaxCube
       private
+      # Gets +MSG_TYPES+ constant depending on object's end-class.
+      # @return [Array<String>] +MSG_TYPES+ constant
+      #   depending on object's end-class.
       def msg_types
         self.class.const_get('MSG_TYPES')
       end
+      # Helper method that is called by {#valid_msg_type} or {#check_msg_type}.
+      # It provides validation or check depending on input flag.
+      # If argument is valid, it assigns the message type to internal variable.
+      # @param msg_type [String] input message type character.
+      # @param check [Boolean] whether to check (raise exception on failure).
       def maybe_check_valid_msg_type(msg_type, check)
         valid = msg_type&.length == 1 &&
                 msg_types.include?(msg_type)
@@ -108,6 +201,16 @@ module MaxCube
         raise InvalidMessageType.new(@msg_type) unless valid
       end
+      # Checks whether given +args+
+      # satisfy lengths specified in input +lengths+.
+      # Missing positions in +lengths+ means
+      # that no requirement is demanded at that index.
+      # @param lengths [Array<Integer>] required lenghts of arguments.
+      # @param args [Array<#length>] arguments to be validated.
+      # @return [Boolean] +true+ if lengths of 'all' +args+
+      #   fits to input +lengths+;
+      #   +false+ otherwise, or if any +arg+ is +nil+,
+      #   or if size of +lengths+ is higher than number of +args+.
       def valid_msg_part_lengths(lengths, *args)
         return false if args.any?(&:nil?) ||
                         args.length < lengths.length
@@ -116,19 +219,42 @@ module MaxCube
         end
       end
+      # As {#valid_msg_part_lengths}, but raises exception on failure.
+      # @return [Array] +args+ if +lengths+ are satisfied.
+      # @raise [InvalidMessageBody] if +lengths+ are _not_ satisfied.
       def check_msg_part_lengths(lengths, *args)
-        return if valid_msg_part_lengths(lengths, *args)
+        return args if valid_msg_part_lengths(lengths, *args)
         raise InvalidMessageBody
           .new(@msg_type,
                "invalid lengths of message parts #{args}" \
                " (lengths should be: #{lengths})")
       end
+      # Helper method that is called
+      # by {#msg_type_hash_keys} or {#msg_type_hash_opt_keys}.
+      # It accesses +KEYS+ or +OPT_KEYS+ (depending on input flag)
+      # from object's concrete end-class.
+      # @param msg_type [String] message type that is being parsed/serialized.
+      # @param optional [Boolean] whether to return optional or mandatory keys.
+      # @return [Array<Symbol>] mandatory or optional hash keys,
+      #   depending on +optional+, related to message type.
+      #   If constant is not found, empty array is returned.
       def msg_type_which_hash_keys(msg_type, optional = false)
         str = "Message#{msg_type.upcase}::" + (optional ? 'OPT_KEYS' : 'KEYS')
         self.class.const_defined?(str) ? self.class.const_get(str) : []
       end
+      # Helper method that is called
+      # by {#valid_hash_keys} or {#check_hash_keys}.
+      # It validates/checks whether given hash contain
+      # all mandatory keys ({#msg_type_hash_keys})
+      # and not other than optional keys ({#msg_type_hash_opt_keys}).
+      # @param hash [Hash] input hash.
+      # @param check [Boolean] whether to check (raise exception on failure).
+      # @return [Boolean] +true+ or +false+ for valid/invalid hash keys
+      #   if +check+ is +false+.
+      # @raise [InvalidMessageBody] if +check+ is +true+
+      #   and hash keys are invalid.
       def maybe_check_valid_hash_keys(hash, check)
         keys = msg_type_hash_keys(@msg_type).dup
         opt_keys = msg_type_hash_opt_keys(@msg_type)
@@ -142,10 +268,18 @@ module MaxCube
                "(should be: #{keys})")
       end
+      # Encodes input binary data to only printable characters
+      # using Base64#strict_encode64.
+      # @param data [String] input raw data string.
+      # @return [String] Base64-encoded string.
       def encode(data)
         Base64.strict_encode64(data)
       end
+      # Decodes input data with only printable characters
+      # to binary data using Base64#decode64.
+      # @param data [String] input Base64-encoded string.
+      # @return [String] raw data string.
       def decode(data)
         Base64.decode64(data)
       end