Merge pull request #17761 from Ladas/ansible_runner_add_missing_yard_…

…docs

Ansible runner add missing yard docs

lib/ansible/runner.rb

@@ -1,18 +1,57 @@
 module Ansible
   class Runner
     class << self
+      # Runs a playbook via ansible-runner, see: https://ansible-runner.readthedocs.io/en/latest/standalone.html#running-playbooks
+      #
+      # @param env_vars [Hash] Hash with key/value pairs that will be passed as environment variables to the
+      #        ansible-runner run
+      # @param extra_vars [Hash] Hash with key/value pairs that will be passed as extra_vars to the ansible-runner run
+      # @param playbook_path [String] Path to the playbook we will want to run
+      # @return [Ansible::Runner::Response] Response object with all details about the ansible run
       def run(env_vars, extra_vars, playbook_path)
         run_via_cli(env_vars, extra_vars, :playbook_path => playbook_path)
       end
 
+      # Runs a role directly via ansible-runner, a simple playbook is then automatically created,
+      # see: https://ansible-runner.readthedocs.io/en/latest/standalone.html#running-roles-directly
+      #
+      # @param env_vars [Hash] Hash with key/value pairs that will be passed as environment variables to the
+      #        ansible-runner run
+      # @param extra_vars [Hash] Hash with key/value pairs that will be passed as extra_vars to the ansible-runner run
+      # @param role_name [String] Ansible role name
+      # @param roles_path [String] Path to the directory with roles
+      # @param role_skip_facts [Boolean] Whether we should skip facts gathering, equals to 'gather_facts: False' in a
+      #        playbook. True by default.
+      # @return [Ansible::Runner::Response] Response object with all details about the ansible run
       def run_role(env_vars, extra_vars, role_name, roles_path:, role_skip_facts: true)
         run_via_cli(env_vars, extra_vars, :role_name => role_name, :roles_path => roles_path, :role_skip_facts => role_skip_facts)
       end
 
+      # Runs "run" method via queue
+      #
+      # @param env_vars [Hash] Hash with key/value pairs that will be passed as environment variables to the
+      #        ansible-runner run
+      # @param extra_vars [Hash] Hash with key/value pairs that will be passed as extra_vars to the ansible-runner run
+      # @param playbook_path [String] Path to the playbook we will want to run
+      # @param user_id [String] Current user identifier
+      # @param queue_opts [Hash] Additional options that will be passed to MiqQueue record creation
+      # @return [BigInt] ID of MiqTask record wrapping the task
       def run_queue(env_vars, extra_vars, playbook_path, user_id, queue_opts)
         run_in_queue("run", user_id, queue_opts, [env_vars, extra_vars, playbook_path])
       end
 
+      # Runs "run_role" method via queue
+      #
+      # @param env_vars [Hash] Hash with key/value pairs that will be passed as environment variables to the
+      #        ansible-runner run
+      # @param extra_vars [Hash] Hash with key/value pairs that will be passed as extra_vars to the ansible-runner run
+      # @param role_name [String] Ansible role name
+      # @param user_id [String] Current user identifier
+      # @param queue_opts [Hash] Additional options that will be passed to MiqQueue record creation
+      # @param roles_path [String] Path to the directory with roles
+      # @param role_skip_facts [Boolean] Whether we should skip facts gathering, equals to 'gather_facts: False' in a
+      #        playbook. True by default.
+      # @return [BigInt] ID of MiqTask record wrapping the task
       def run_role_queue(env_vars, extra_vars, role_name, user_id, queue_opts, roles_path:, role_skip_facts: true)
         run_in_queue("run_role",
                      user_id,
@@ -22,6 +61,13 @@ def run_role_queue(env_vars, extra_vars, role_name, user_id, queue_opts, roles_p
 
       private
 
+      # Run a method on self class, via queue, executed by generic worker
+      #
+      # @param method_name [String] A public method name on self
+      # @param user_id [String] Current user identifier
+      # @param queue_opts [Hash] Additional options that will be passed to MiqQueue record creation
+      # @param args [Array] Arguments that will be passed to the <method_name> method
+      # @return [BigInt] ID of MiqTask record wrapping the task
       def run_in_queue(method_name, user_id, queue_opts, args)
         queue_opts = {
           :args        => args,
@@ -38,6 +84,17 @@ def run_in_queue(method_name, user_id, queue_opts, args)
         MiqTask.generic_action_with_callback(task_opts, queue_opts)
       end
 
+      # Runs a playbook or a role via ansible-runner.
+      #
+      # @param env_vars [Hash] Hash with key/value pairs that will be passed as environment variables to the
+      #        ansible-runner run
+      # @param extra_vars [Hash] Hash with key/value pairs that will be passed as extra_vars to the ansible-runner run
+      # @param playbook_path [String] Path to the playbook we will want to run
+      # @param role_name [String] Ansible role name
+      # @param roles_path [String] Path to the directory with roles
+      # @param role_skip_facts [Boolean] Whether we should skip facts gathering, equals to 'gather_facts: False' in a
+      #        playbook. True by default.
+      # @return [Ansible::Runner::Response] Response object with all details about the ansible run
       def run_via_cli(env_vars, extra_vars, playbook_path: nil, role_name: nil, roles_path: nil, role_skip_facts: true)
         validate_params!(env_vars, extra_vars, playbook_path, roles_path)
 
@@ -56,6 +113,15 @@ def run_via_cli(env_vars, extra_vars, playbook_path: nil, role_name: nil, roles_
         end
       end
 
+      # Generate correct params, depending if we've passed :playbook_path or a :role_name
+      #
+      # @param extra_vars [Hash] Hash with key/value pairs that will be passed as extra_vars to the ansible-runner run
+      # @param playbook_path [String] Path to the playbook we will want to run
+      # @param role_name [String] Ansible role name
+      # @param roles_path [String] Path to the directory with roles
+      # @param role_skip_facts [Boolean] Whether we should skip facts gathering, equals to 'gather_facts: False' in a
+      #        playbook.
+      # @return [Array] Arguments for the ansible-runner run
       def params(extra_vars:, playbook_path:, role_name:, roles_path:, role_skip_facts:)
         role_or_playbook_params = if playbook_path
                                     playbook_params(:playbook_path => playbook_path)
@@ -68,10 +134,21 @@ def params(extra_vars:, playbook_path:, role_name:, roles_path:, role_skip_facts
         [shared_params(:extra_vars => extra_vars).merge(role_or_playbook_params)]
       end
 
+      # Generate correct params if using :playbook_path
+      #
+      # @param playbook_path [String] Path to the playbook we will want to run
+      # @return [Hash] Partial arguments for the ansible-runner run
       def playbook_params(playbook_path:)
         {:playbook => playbook_path}
       end
 
+      # Generate correct params if using :role_name
+      #
+      # @param role_name [String] Ansible role name
+      # @param roles_path [String] Path to the directory with roles
+      # @param role_skip_facts [Boolean] Whether we should skip facts gathering, equals to 'gather_facts: False' in a
+      #        playbook.
+      # @return [Hash] Partial arguments for the ansible-runner run
       def role_params(role_name:, roles_path:, role_skip_facts:)
         role_params = {:role => role_name}
 
@@ -81,30 +158,50 @@ def role_params(role_name:, roles_path:, role_skip_facts:)
         role_params
       end
 
+      # Generate correct params shared by :playbook_path or a :role_name paths
+      #
+      # @param extra_vars [Hash] Hash with key/value pairs that will be passed as extra_vars to the ansible-runner run
+      # @return [Hash] Partial arguments for the ansible-runner run
       def shared_params(extra_vars:)
         {:cmdline => "--extra-vars '#{JSON.dump(extra_vars)}'"}
       end
 
+      # Reads a return code from a file used by ansible-runner
+      #
+      # @return [Integer] Return code of the ansible-runner run, 0 == ok, others mean failure
       def return_code(base_dir)
         File.read(File.join(base_dir, "artifacts/result/rc")).to_i
       rescue
         _log.warn("Couldn't find ansible-runner return code")
         1
       end
 
+      # Asserts passed parameters are correct, if not throws an exception.
+      #
+      # @param env_vars [Hash] Hash with key/value pairs that will be passed as environment variables to the
+      #        ansible-runner run
+      # @param extra_vars [Hash] Hash with key/value pairs that will be passed as extra_vars to the ansible-runner run
+      # @param playbook_path [String] Path to the playbook we will want to run
+      # @param roles_path [String] Path to the directory with roles
       def validate_params!(env_vars, extra_vars, playbook_path, roles_path)
         assert_hash!(env_vars)
         assert_hash!(extra_vars)
         assert_path!(playbook_path)
         assert_path!(roles_path)
       end
 
+      # Asserts that passed argument is a hash
+      #
+      # @param hash [Hash] Passed argument we test for being Hash
       def assert_hash!(hash)
         unless hash.kind_of?(Hash)
           raise "Passed parameter must be of type Hash, got: #{hash}"
         end
       end
 
+      # Asserts that passed path exists
+      #
+      # @param path [Hash, NilClass] Passed path we test for existence
       def assert_path!(path)
         return unless path
 
@@ -113,6 +210,7 @@ def assert_path!(path)
         end
       end
 
+      # @return [String] ansible_runner executable command
       def ansible_command(base_dir)
         "ansible-runner run #{base_dir} --json -i result --hosts localhost"
       end

lib/ansible/runner/response.rb

@@ -5,6 +5,11 @@ class Response
 
       attr_reader :return_code, :stdout, :stderr, :parsed_stdout
 
+      # Response object designed for holding full response from ansible-runner
+      #
+      # @param return_code [Integer] Return code of the ansible-runner run, 0 == ok, others mean failure
+      # @param stdout [String] Stdout from ansible-runner run
+      # @param stderr [String] Stderr from ansible-runner run
       def initialize(return_code:, stdout:, stderr:)
         @return_code   = return_code
         @stdout        = stdout
@@ -14,6 +19,10 @@ def initialize(return_code:, stdout:, stderr:)
 
       private
 
+      # Parses stdout to array of hashes
+      #
+      # @param stdout [String] Stdout that is text, where each line should be JSON encoded object
+      # @return [Array<Hash>] Array of hashes as individual Ansible plays
       def parse_stdout(stdout)
         parsed_stdout = []