kitchen-docker 3.3.0 → 3.3.3

data/Rakefile

@@ -16,4 +16,22 @@ rescue LoadError
   puts "cookstyle/chefstyle is not available. (sudo) gem install cookstyle to do style checking."
 end
 
+begin
+  require "yard"
+
+  # Options and the file list live in .yardopts so that a bare `yard` from the
+  # command line produces exactly what `rake doc` does.
+  YARD::Rake::YardocTask.new(:doc)
+
+  desc "List anything in lib/ that is still undocumented"
+  task :doc_coverage do
+    sh "yard stats --list-undoc"
+  end
+rescue LoadError
+  desc "Generate YARD documentation (not installed)"
+  task :doc do
+    abort "YARD is not installed. Run: bundle install"
+  end
+end
+
 task default: %i{style test}

data/lib/kitchen/docker/container/linux.rb

@@ -22,15 +22,28 @@ require_relative "../helpers/dockerfile_helper"
 module Kitchen
   module Docker
     class Container
+      # A Linux container, reached over SSH.
+      #
+      # The generated image installs and runs an SSH server, and Test Kitchen
+      # connects to a published port with a generated key. That is why the
+      # Dockerfile here is so much larger than the Windows one.
       class Linux < Kitchen::Docker::Container
         include Kitchen::Docker::Helpers::DockerfileHelper
 
+        # Serializes SSH key generation across concurrently running instances,
+        # which share one key path.
         MUTEX_FOR_SSH_KEYS = Mutex.new
 
+        # @param config [Hash] the driver configuration
         def initialize(config)
           super
         end
 
+        # Builds the image, runs the container, and publishes its SSH port.
+        #
+        # @param state [Hash] mutable instance state; gains +ssh_key+, +image_id+,
+        #   +container_id+, +hostname+, and +port+
+        # @return [void]
         def create(state)
           super
 
@@ -44,6 +57,15 @@ module Kitchen
           state[:port] = container_ssh_port(state)
         end
 
+        # Runs a command in the container by uploading it as a shell script.
+        #
+        # The command is written to a temp file and executed with bash rather than
+        # passed on the command line, which keeps long converge scripts clear of
+        # argument-length and quoting limits.
+        #
+        # @param command [String] the shell code to run
+        # @return [String] the command's combined output
+        # @raise [RuntimeError] if the command fails
         def execute(command)
           # Create temp script file and upload files to container
           debug("Executing command on Linux container (Platform: #{@config[:platform]})")
@@ -58,9 +80,6 @@ module Kitchen
           debug("Uploading temp file #{temp_file} to #{remote_path} on container")
           upload(temp_file, remote_path)
 
-          debug("Deleting temp file from local filesystem")
-          ::File.delete(temp_file)
-
           # Replace any environment variables used in the path and execute script file
           debug("Executing temp script #{remote_path}/#{filename} on container")
           remote_path = replace_env_variables(@config, remote_path)
@@ -68,10 +87,23 @@ module Kitchen
           container_exec(@config, "/bin/bash #{remote_path}/#{filename}")
         rescue => e
           raise "Failed to execute command on Linux container. #{e}"
+        ensure
+          # Removed here rather than after the upload, so that a failure part
+          # way through does not leave the script behind in .kitchen/temp.
+          if temp_file && ::File.exist?(temp_file)
+            debug("Deleting temp file from local filesystem")
+            ::File.delete(temp_file)
+          end
         end
 
         protected
 
+        # Generates the SSH keypair used to log into Linux containers.
+        #
+        # Guarded by {MUTEX_FOR_SSH_KEYS} because concurrent instances share one
+        # key path and would otherwise write the file while another reads it.
+        #
+        # @return [void]
         def generate_keys
           MUTEX_FOR_SSH_KEYS.synchronize do
             if !File.exist?(@config[:public_key]) || !File.exist?(@config[:private_key])
@@ -90,13 +122,40 @@ module Kitchen
           end
         end
 
+        # Pulls the published port out of `docker port` output.
+        #
+        # One line is printed per published binding, and the host part varies:
+        #
+        #   0.0.0.0:32768
+        #   [::]:32768
+        #
+        # The port is taken from the end of the line rather than by splitting on
+        # ":" from the left, because an IPv6 host contains colons of its own --
+        # splitting left-to-right returned "" for those, and "".to_i is 0, so a
+        # daemon publishing on IPv6 handed Test Kitchen port 0 to connect to.
+        #
+        # @param output [String] e.g. +"0.0.0.0:32768\n[::]:32768\n"+
+        # @return [Integer] the host-side port
+        # @raise [Kitchen::ActionFailed] if no port could be found
         def parse_container_ssh_port(output)
-          _host, port = output.split(":")
+          port = output.lines.filter_map { |line| line[/:(\d+)\s*\z/, 1] }.first
+
+          if port.nil?
+            raise ActionFailed, "Could not parse Docker port output for container SSH port: #{output.inspect}"
+          end
+
           port.to_i
-        rescue => e
-          raise ActionFailed, "Could not parse Docker port output for container SSH port. #{e}"
         end
 
+        # The port Test Kitchen should connect to for SSH.
+        #
+        # On the internal Docker network the container is reached directly, so the
+        # unmapped port 22 is correct; otherwise Docker's published mapping is
+        # looked up.
+        #
+        # @param state [Hash] instance state naming the container
+        # @return [Integer] the port to connect on
+        # @raise [Kitchen::ActionFailed] if no SSH port is mapped
         def container_ssh_port(state)
           return 22 if @config[:use_internal_docker_network]
 
@@ -106,6 +165,14 @@ module Kitchen
           raise ActionFailed, "Docker reports container has no ssh port mapped. #{e}"
         end
 
+        # Builds the Dockerfile for a Linux container.
+        #
+        # A configured +dockerfile+ is used as-is after ERB rendering. Otherwise
+        # one is generated: the base image, proxy settings, the platform's own
+        # package setup, any +provision_command+ entries, and the generated public
+        # key appended to the login user's authorized_keys.
+        #
+        # @return [String] the Dockerfile contents
         def dockerfile
           return dockerfile_template if @config[:dockerfile]
 

data/lib/kitchen/docker/container/windows.rb

@@ -18,11 +18,25 @@ require_relative "../container"
 module Kitchen
   module Docker
     class Container
+      # A Windows container, driven through `docker exec`.
+      #
+      # There is no SSH server and no key to inject: commands are uploaded as
+      # PowerShell scripts and executed in the container directly, so no port
+      # is published.
       class Windows < Kitchen::Docker::Container
+        # @param config [Hash] the driver configuration
         def initialize(config)
           super
         end
 
+        # Builds the image and runs the container.
+        #
+        # No port is published: Windows containers are driven through `docker exec`
+        # rather than SSH, so there is nothing to map.
+        #
+        # @param state [Hash] mutable instance state; gains +username+, +image_id+,
+        #   +container_id+, and +hostname+
+        # @return [void]
         def create(state)
           super
 
@@ -33,6 +47,11 @@ module Kitchen
           state[:hostname] = hostname(state)
         end
 
+        # Runs a command in the container by uploading it as a PowerShell script.
+        #
+        # @param command [String] the PowerShell code to run
+        # @return [String] the command's combined output
+        # @raise [RuntimeError] if the command fails
         def execute(command)
           # Create temp script file and upload files to container
           debug("Executing command on Windows container")
@@ -47,9 +66,6 @@ module Kitchen
           debug("Uploading temp file #{temp_file} to #{remote_path} on container")
           upload(temp_file, remote_path)
 
-          debug("Deleting temp file from local filesystem")
-          ::File.delete(temp_file)
-
           # Replace any environment variables used in the path and execute script file
           debug("Executing temp script #{remote_path}\\#{filename} on container")
           remote_path = replace_env_variables(@config, remote_path)
@@ -58,10 +74,25 @@ module Kitchen
           container_exec(@config, cmd)
         rescue => e
           raise "Failed to execute command on Windows container. #{e}"
+        ensure
+          # Removed here rather than after the upload, so that a failure part
+          # way through does not leave the script behind in .kitchen/temp.
+          if temp_file && ::File.exist?(temp_file)
+            debug("Deleting temp file from local filesystem")
+            ::File.delete(temp_file)
+          end
         end
 
         protected
 
+        # Builds the Dockerfile for a Windows container.
+        #
+        # Much shorter than the Linux equivalent: there is no SSH server and no
+        # key to inject, so only the base image, proxy settings, and any
+        # +provision_command+ entries are emitted.
+        #
+        # @return [String] the Dockerfile contents
+        # @raise [Kitchen::ActionFailed] if the platform is not +windows+
         def dockerfile
           raise ActionFailed, "Unknown platform '#{@config[:platform]}'" unless @config[:platform] == "windows"
           return dockerfile_template if @config[:dockerfile]

data/lib/kitchen/docker/container.rb

@@ -18,20 +18,47 @@ require_relative "helpers/image_helper"
 
 module Kitchen
   module Docker
+    # Base class for the container the instance under test runs in.
+    #
+    # Holds the behaviour that is the same on every platform -- checking
+    # whether the container exists, removing it, working out its address, and
+    # copying files in. {Linux} and {Windows} add how the image is built and
+    # how commands are run, which share almost nothing.
     class Container
       include Kitchen::Docker::Helpers::CliHelper
       include Kitchen::Docker::Helpers::ContainerHelper
       include Kitchen::Docker::Helpers::FileHelper
       include Kitchen::Docker::Helpers::ImageHelper
 
+      # @param config [Hash] the driver or transport configuration
       def initialize(config)
         @config = config
       end
 
+      # Checks the container named in state and records the login user.
+      #
+      # A state file naming a container that no longer exists is an error rather
+      # than something to build over, because the stale id usually means the
+      # container was removed behind Test Kitchen's back and silently creating a
+      # new one would hide that.
+      #
+      # A container that exists but has stopped is also an error, and a separate
+      # one: it is still there to be cleaned up, so the message points at
+      # `kitchen destroy` rather than claiming the container is gone.
+      #
+      # @param state [Hash] mutable instance state; gains +username+
+      # @return [void]
+      # @raise [Kitchen::ActionFailed] if state names a container that is gone,
+      #   or one that exists but is not running
       def create(state)
         if container_exists?(state)
+          unless container_running?(state)
+            raise ActionFailed, "Container ID #{state[:container_id]} was found in the kitchen state data, " \
+                                "but the container is not running. Run `kitchen destroy` to remove it."
+          end
+
           info("Container ID #{state[:container_id]} already exists.")
-        elsif !container_exists?(state) && state[:container_id]
+        elsif state[:container_id]
           raise ActionFailed, "Container ID #{state[:container_id]} was found in the kitchen state data, " \
                               "but the container does not exist."
         end
@@ -39,6 +66,10 @@ module Kitchen
         state[:username] = @config[:username]
       end
 
+      # Removes the container, and its image when +remove_images+ is set.
+      #
+      # @param state [Hash] instance state naming the container
+      # @return [void]
       def destroy(state)
         info("[Docker] Destroying Docker container #{state[:container_id]}") if state[:container_id]
         remove_container(state) if container_exists?(state)
@@ -48,6 +79,14 @@ module Kitchen
         end
       end
 
+      # Works out the address Test Kitchen should connect to.
+      #
+      # A remote Docker socket means the container is reachable at the socket's
+      # own host; +use_internal_docker_network+ means its container IP; anything
+      # else is a published port on localhost.
+      #
+      # @param state [Hash] instance state naming the container
+      # @return [String] a hostname or IP address
       def hostname(state)
         hostname = "localhost"
 
@@ -60,6 +99,11 @@ module Kitchen
         hostname
       end
 
+      # Copies local files into the container.
+      #
+      # @param locals [String, Array<String>] one path or several
+      # @param remote [String] destination path inside the container
+      # @return [Array<String>] the files copied
       def upload(locals, remote)
         files = locals
         files = Array(locals) unless locals.is_a?(Array)

data/lib/kitchen/docker/docker_version.rb

@@ -13,9 +13,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# Test Kitchen's top-level namespace.
 module Kitchen
+  # Everything belonging to the kitchen-docker plugin.
   module Docker
-    # Version string for Docker Kitchen driver
-    DOCKER_VERSION = "3.3.0".freeze
+    # The version of the kitchen-docker gem.
+    DOCKER_VERSION = "3.3.3".freeze
   end
 end

data/lib/kitchen/docker/erb_context.rb

@@ -17,13 +17,22 @@ require "erb" unless defined?(Erb)
 
 module Kitchen
   module Docker
+    # Evaluation context for a user-supplied Dockerfile template.
+    #
+    # Each configuration key becomes an instance variable, so a template can
+    # refer to +@image+, +@username+, and the rest.
     class ERBContext
+      # Exposes each config key to the template as an instance variable, so a
+      # custom Dockerfile can refer to +@image+, +@username+, and the rest.
+      #
+      # @param config [Hash] the configuration to expose
       def initialize(config = {})
         config.each do |key, value|
           instance_variable_set("@" + key.to_s, value)
         end
       end
 
+      # @return [Binding] a binding for ERB to evaluate the template in
       def get_binding
         binding
       end

data/lib/kitchen/docker/helpers/cli_helper.rb

@@ -15,32 +15,71 @@ require "kitchen"
 require "kitchen/configurable"
 require "kitchen/logging"
 require "kitchen/shell_out"
+require "shellwords" unless defined?(Shellwords)
 
 module Kitchen
   module Docker
+    # Mixins shared by the driver, transport, and container classes.
     module Helpers
-      # rubocop:disable Metrics/ModuleLength, Style/Documentation
+      # rubocop:disable Metrics/ModuleLength
+      # Builds and runs docker CLI command lines.
       module CliHelper
         include Configurable
         include Logging
         include ShellOut
 
+        # Escapes a configured value for the shell.
+        #
+        # Docker command lines are assembled as strings and handed to a shell, so
+        # a value that is a single datum -- a path, a name, a port mapping -- has
+        # to be escaped, or a space inside it is read as an argument separator and
+        # the rest of the value is taken as the image name.
+        #
+        # Values that are deliberately shell fragments are *not* escaped:
+        # +run_command+, +run_options+, +build_options+, and the command handed to
+        # `docker exec` are all documented as accepting flags and arguments.
+        #
+        # Escaping is a no-op for ordinary values -- +db:db+ and +8.8.8.8+ come
+        # back unchanged -- so this only alters command lines that were already
+        # broken.
+        #
+        # @param value [#to_s] the configured value
+        # @return [String] the value, safe to interpolate into a command line
+        def shell_escape(value)
+          Shellwords.escape(value.to_s)
+        end
+
         # rubocop:disable Metrics/AbcSize
+
+        # Runs a docker CLI command with the configured connection flags.
+        #
+        # @param cmd [String] the docker subcommand and its arguments
+        # @param options [Hash] shell-out options
+        # @return [String] the command's combined stdout and stderr
         def docker_command(cmd, options = {})
           docker = config[:binary].dup
-          docker << " -H #{config[:socket]}" if config[:socket]
+          docker << " -H #{shell_escape(config[:socket])}" if config[:socket]
           docker << " --tls" if config[:tls]
           docker << " --tlsverify" if config[:tls_verify]
-          docker << " --tlscacert=#{config[:tls_cacert]}" if config[:tls_cacert]
-          docker << " --tlscert=#{config[:tls_cert]}" if config[:tls_cert]
-          docker << " --tlskey=#{config[:tls_key]}" if config[:tls_key]
+          docker << " --tlscacert=#{shell_escape(config[:tls_cacert])}" if config[:tls_cacert]
+          docker << " --tlscert=#{shell_escape(config[:tls_cert])}" if config[:tls_cert]
+          docker << " --tlskey=#{shell_escape(config[:tls_key])}" if config[:tls_key]
           logger.debug("docker_command: #{docker} #{cmd} shell_opts: #{docker_shell_opts(options)}")
           run_command("#{docker} #{cmd}", docker_shell_opts(options))
         end
         # rubocop:enable Metrics/AbcSize
 
-        # Copied from kitchen because we need stderr
         # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+
+        # Runs a shell command, returning stderr as well as stdout.
+        #
+        # Test Kitchen's own +run_command+ discards stderr, but docker writes build
+        # progress and image ids there, so this reimplements it to keep both.
+        #
+        # @param cmd [String] the command to run
+        # @param options [Hash] shell-out options
+        # @return [String] combined stdout and stderr
+        # @raise [Kitchen::ShellCommandFailed] if the command exits non-zero
         def run_command(cmd, options = {})
           if options.fetch(:use_sudo, false)
             cmd = "#{options.fetch(:sudo_command, "sudo -E")} #{cmd}"
@@ -62,44 +101,57 @@ module Kitchen
         # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
 
         # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength, Metrics/AbcSize
+
+        # Builds the `docker run` command line from the configuration.
+        #
+        # @param image_id [String] the image to run
+        # @param transport_port [Integer, nil] container port to publish, if any
+        # @return [String] the docker subcommand and its arguments
         def build_run_command(image_id, transport_port = nil)
           cmd = "run -d"
           cmd << " -i" if config[:interactive]
           cmd << " -t" if config[:tty]
           cmd << build_env_variable_args(config[:env_variables]) if config[:env_variables]
           cmd << " -p #{transport_port}" unless transport_port.nil?
-          Array(config[:forward]).each { |port| cmd << " -p #{port}" }
-          Array(config[:dns]).each { |dns| cmd << " --dns #{dns}" }
-          Array(config[:add_host]).each { |host, ip| cmd << " --add-host=#{host}:#{ip}" }
-          Array(config[:volume]).each { |volume| cmd << " -v #{volume}" }
-          Array(config[:volumes_from]).each { |container| cmd << " --volumes-from #{container}" }
-          Array(config[:links]).each { |link| cmd << " --link #{link}" }
-          Array(config[:devices]).each { |device| cmd << " --device #{device}" }
-          Array(config[:mount]).each { |mount| cmd << " --mount #{mount}" }
-          Array(config[:tmpfs]).each { |tmpfs| cmd << " --tmpfs #{tmpfs}" }
-          cmd << " --name #{config[:instance_name]}" if config[:instance_name]
+          Array(config[:forward]).each { |port| cmd << " -p #{shell_escape(port)}" }
+          Array(config[:dns]).each { |dns| cmd << " --dns #{shell_escape(dns)}" }
+          Array(config[:add_host]).each { |host, ip| cmd << " --add-host=#{shell_escape("#{host}:#{ip}")}" }
+          Array(config[:volume]).each { |volume| cmd << " -v #{shell_escape(volume)}" }
+          Array(config[:volumes_from]).each { |container| cmd << " --volumes-from #{shell_escape(container)}" }
+          Array(config[:links]).each { |link| cmd << " --link #{shell_escape(link)}" }
+          Array(config[:devices]).each { |device| cmd << " --device #{shell_escape(device)}" }
+          Array(config[:mount]).each { |mount| cmd << " --mount #{shell_escape(mount)}" }
+          Array(config[:tmpfs]).each { |tmpfs| cmd << " --tmpfs #{shell_escape(tmpfs)}" }
+          cmd << " --name #{shell_escape(config[:instance_name])}" if config[:instance_name]
           cmd << " -P" if config[:publish_all]
-          cmd << " -h #{config[:hostname]}" if config[:hostname]
-          cmd << " -m #{config[:memory]}" if config[:memory]
-          cmd << " -c #{config[:cpu]}" if config[:cpu]
-          cmd << " --gpus #{config[:gpus]}" if config[:gpus]
-          cmd << " -e http_proxy=#{config[:http_proxy]}" if config[:http_proxy]
-          cmd << " -e https_proxy=#{config[:https_proxy]}" if config[:https_proxy]
+          cmd << " -h #{shell_escape(config[:hostname])}" if config[:hostname]
+          cmd << " -m #{shell_escape(config[:memory])}" if config[:memory]
+          cmd << " -c #{shell_escape(config[:cpu])}" if config[:cpu]
+          cmd << " --gpus #{shell_escape(config[:gpus])}" if config[:gpus]
+          cmd << " -e http_proxy=#{shell_escape(config[:http_proxy])}" if config[:http_proxy]
+          cmd << " -e https_proxy=#{shell_escape(config[:https_proxy])}" if config[:https_proxy]
           cmd << " --privileged" if config[:privileged]
-          cmd << " --isolation #{config[:isolation]}" if config[:isolation]
-          Array(config[:cap_add]).each { |cap| cmd << " --cap-add=#{cap}" } if config[:cap_add]
-          Array(config[:cap_drop]).each { |cap| cmd << " --cap-drop=#{cap}" } if config[:cap_drop]
-          Array(config[:security_opt]).each { |opt| cmd << " --security-opt=#{opt}" } if config[:security_opt]
-          cmd << " --platform=#{config[:docker_platform]}" if config[:docker_platform]
+          cmd << " --isolation #{shell_escape(config[:isolation])}" if config[:isolation]
+          Array(config[:cap_add]).each { |cap| cmd << " --cap-add=#{shell_escape(cap)}" } if config[:cap_add]
+          Array(config[:cap_drop]).each { |cap| cmd << " --cap-drop=#{shell_escape(cap)}" } if config[:cap_drop]
+          Array(config[:security_opt]).each { |opt| cmd << " --security-opt=#{shell_escape(opt)}" } if config[:security_opt]
+          cmd << " --platform=#{shell_escape(config[:docker_platform])}" if config[:docker_platform]
           extra_run_options = config_to_options(config[:run_options])
           cmd << " #{extra_run_options}" unless extra_run_options.empty?
-          cmd << " #{image_id} #{config[:run_command]}"
+          # run_command is a command line, not a single value, so it stays raw.
+          cmd << " #{shell_escape(image_id)} #{config[:run_command]}"
           logger.debug("build_run_command: #{cmd}")
           cmd
         end
         # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength, Metrics/AbcSize
 
         # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize
+
+        # Builds a `docker exec` command line from the configuration.
+        #
+        # @param state [Hash] instance state naming the container
+        # @param command [String] the command to run inside it
+        # @return [String] the docker subcommand and its arguments
         def build_exec_command(state, command)
           cmd = "exec"
           cmd << " -d" if config[:detach]
@@ -107,22 +159,33 @@ module Kitchen
           cmd << " --privileged" if config[:privileged]
           cmd << " -t" if config[:tty]
           cmd << " -i" if config[:interactive]
-          cmd << " -u #{config[:username]}" if config[:username]
-          cmd << " -w #{config[:working_dir]}" if config[:working_dir]
-          cmd << " #{state[:container_id]}"
+          cmd << " -u #{shell_escape(config[:username])}" if config[:username]
+          cmd << " -w #{shell_escape(config[:working_dir])}" if config[:working_dir]
+          cmd << " #{shell_escape(state[:container_id])}"
+          # command is a command line, not a single value, so it stays raw.
           cmd << " #{command}"
           logger.debug("build_exec_command: #{cmd}")
           cmd
         end
         # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize
 
+        # Builds a `docker cp` command line.
+        #
+        # @param local_file [String] source path
+        # @param remote_file [String] destination, as +container:path+
+        # @param opts [Hash] +:archive+ to preserve ownership and mode
+        # @return [String] the docker subcommand and its arguments
         def build_copy_command(local_file, remote_file, opts = {})
           cmd = "cp"
           cmd << " -a" if opts[:archive]
-          cmd << " #{local_file} #{remote_file}"
+          cmd << " #{shell_escape(local_file)} #{shell_escape(remote_file)}"
           cmd
         end
 
+        # Wraps PowerShell code so it can be run through `docker exec`.
+        #
+        # @param args [String] the PowerShell arguments
+        # @return [String] the full powershell invocation
         def build_powershell_command(args)
           cmd = "powershell -ExecutionPolicy Bypass -NoLogo "
           cmd << args
@@ -130,17 +193,24 @@ module Kitchen
           cmd
         end
 
+        # Turns a hash of environment variables into `-e` flags.
+        #
+        # @param vars [Hash] variable names to values
+        # @return [String] the flags, each preceded by a space
+        # @raise [Kitchen::ActionFailed] if given something other than a Hash
         def build_env_variable_args(vars)
           raise ActionFailed, "Environment variables are not of a Hash type" unless vars.is_a?(Hash)
 
           args = ""
           vars.each do |k, v|
-            args << " -e #{k.to_s.strip}=\"#{v.to_s.strip}\""
+            args << " -e #{shell_escape("#{k.to_s.strip}=#{v.to_s.strip}")}"
           end
 
           args
         end
 
+        # @return [String] the platform's null device, +NUL+ on Windows and
+        #   +/dev/null+ everywhere else
         def dev_null
           case RbConfig::CONFIG["host_os"]
           when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
@@ -150,6 +220,13 @@ module Kitchen
           end
         end
 
+        # Normalizes shell-out options for a docker command.
+        #
+        # Translates +:suppress_output+ into silencing the live stream, and removes
+        # it, since Mixlib::ShellOut would reject the unknown key.
+        #
+        # @param options [Hash] the options to normalize
+        # @return [Hash] options Mixlib::ShellOut accepts
         def docker_shell_opts(options = {})
           options[:live_stream] = nil if options[:suppress_output]
           options.delete(:suppress_output)
@@ -178,7 +255,7 @@ module Kitchen
         end
         # rubocop:enable Metrics/CyclomaticComplexity
       end
-      # rubocop:enable Metrics/ModuleLength, Style/Documentation
+      # rubocop:enable Metrics/ModuleLength
     end
   end
 end