docs: add missing @return tags to every method

lib/kitchen/driver/cloudstack.rb

@@ -247,6 +247,10 @@ def apply_credentials(state, server_info)
 
       # CloudStack's cloud-set-guest-password and SSH key injection can land
       # after the network is up, so allow configuring a settling period.
+      #
+      # Does nothing unless +cloudstack_sync_time+ is set.
+      #
+      # @return [void]
       def wait_for_guest_password_sync
         sync_time = config[:cloudstack_sync_time]
         return unless sync_time
@@ -279,6 +283,8 @@ def networking
 
       # The port the configured transport connects on: 22 for SSH, 5985 or
       # 5986 for WinRM. Port forwarding and firewall rules follow it.
+      #
+      # @return [Integer] the transport's port
       def transport_port
         instance.transport[:port]
       end

lib/kitchen/driver/cloudstack/client.rb

@@ -137,6 +137,18 @@ def job_error(response)
 
           result["errortext"] || result.inspect
         end
+
+        # Types for the private readers above. YARD only honours an attribute
+        # directive that comes after the attr_reader statement, and attaching
+        # one directly to the statement documents only its first name, so the
+        # two are documented together down here instead.
+
+        # @!attribute [r] config
+        #   @return [Hash] the driver configuration
+
+        # @!attribute [r] sleeper
+        #   @return [#call] called with a number of seconds to wait between
+        #     polls of a running job
       end
     end
   end

lib/kitchen/driver/cloudstack/credentials.rb

@@ -31,6 +31,11 @@ class Credentials
         # never authenticate. Users hit this by exporting the wrong half.
         PUBLIC_KEY_PREFIXES = %w{ssh-rsa ssh-dsa ssh-ed25519 ecdsa-sha2-nistp256}.freeze
 
+        # Problems found while resolving credentials, worth telling the user
+        # about but not worth failing over.
+        #
+        # @return [Array<String>] messages collected so far, empty until
+        #   {#to_state} has run
         attr_reader :warnings
 
         # @param config [Hash] the driver configuration
@@ -88,6 +93,12 @@ def generated_password(server_info)
 
         # CloudStack keypairs are matched to a local <name>.pem file. Look in
         # the configured directory first, then the conventional locations.
+        #
+        # Memoized, including the nil result, so the filesystem is searched
+        # once and a missing key is only warned about once.
+        #
+        # @return [String, nil] path to the private key, or nil when no
+        #   keypair is configured or no matching .pem was found
         def keypair_path
           return @keypair_path if defined?(@keypair_path)
 
@@ -138,6 +149,22 @@ def warn_unless_private_key(path)
 
           warnings << "SSH key #{path} is not a private key. Please check your kitchen.yml."
         end
+
+        # Types for the private readers above. YARD only honours an attribute
+        # directive that comes after the attr_reader statement, and attaching
+        # one directly to the statement documents only its first name, so the
+        # three are documented together down here instead.
+
+        # @!attribute [r] config
+        #   @return [Hash] the driver configuration
+
+        # @!attribute [r] home
+        #   @return [String, nil] the home directory keypair paths expand
+        #     against
+
+        # @!attribute [r] working_dir
+        #   @return [String] the directory relative keypair paths expand
+        #     against
       end
     end
   end

lib/kitchen/driver/cloudstack/networking.rb

@@ -164,13 +164,35 @@ def tolerating_missing(description)
         end
 
         # A VPC network needs its vpcid passed when allocating an address.
+        #
+        # @return [String, nil] the configured network's VPC id, or nil when
+        #   the network is not in a VPC, is unknown, or cannot be listed
         def vpc_id
           networks = compute.list_networks.fetch("listnetworksresponse", {})["network"]
           return nil unless networks.is_a?(Array)
 
           network = networks.find { |n| n["id"] == config[:cloudstack_network_id] }
           network && network["vpcid"]
         end
+
+        # Types for the private readers above. YARD only honours an attribute
+        # directive that comes after the attr_reader statement, and attaching
+        # one directly to the statement documents only its first name, so the
+        # four are documented together down here instead.
+
+        # @!attribute [r] config
+        #   @return [Hash] the driver configuration
+
+        # @!attribute [r] client
+        #   @return [Client] the shared CloudStack client, used for its
+        #     connection and its async job handling
+
+        # @!attribute [r] port
+        #   @return [Integer] the transport port that is forwarded and opened
+
+        # @!attribute [r] logger
+        #   @return [#debug, nil] where already-gone resources are noted
+        #     during teardown; nil silences those messages
       end
     end
   end

lib/kitchen/driver/cloudstack/server_options.rb

@@ -27,7 +27,8 @@ class ServerOptions
         # CloudStack rejects instance names longer than this.
         MAX_NAME_LENGTH = 64
 
-        # Random suffix appended to generated names, plus its separator.
+        # Length of the random suffix appended to a generated name. The
+        # separators are budgeted for separately, in {#generate_name}.
         SUFFIX_LENGTH = 8
 
         # Optional parameters, keyed by the CloudStack parameter name. Any
@@ -98,6 +99,9 @@ def display_name
         # The three descriptive parts are truncated proportionally until the
         # whole name fits, so an oversized login or hostname cannot push the
         # result over the limit.
+        #
+        # @return [String] a name of at most {MAX_NAME_LENGTH} characters,
+        #   ending in a random suffix
         def generate_name
           suffix = Array.new(SUFFIX_LENGTH) { rand(36).to_s(36) }.join
           parts = [instance_name, login, hostname].compact.reject(&:empty?)
@@ -135,6 +139,23 @@ def userdata
           data = config[:cloudstack_userdata]
           data.match(BASE64_PATTERN) ? data : Base64.encode64(data)
         end
+
+        # Types for the private readers above. YARD only honours an attribute
+        # directive that comes after the attr_reader statement, and attaching
+        # one directly to the statement documents only its first name, so the
+        # four are documented together down here instead.
+
+        # @!attribute [r] config
+        #   @return [Hash] the driver configuration
+
+        # @!attribute [r] instance_name
+        #   @return [String] the Test Kitchen instance name
+
+        # @!attribute [r] login
+        #   @return [String, nil] the local username, used in a generated name
+
+        # @!attribute [r] hostname
+        #   @return [String, nil] the local hostname, used in a generated name
       end
     end
   end