[docs] YARD: avoid warnings and check the docs

.yardopts

@@ -1,5 +1,8 @@
 --output doc/yard
 --exclude features/
+--exclude bin/bootstrap
+--exclude bin/test
+--exclude license
 --verbose
 --markup-provider kramdown
 --markup markdown

Gemfile

@@ -44,6 +44,13 @@ group :development, :test do
   # Code Coverage
   gem 'simplecov', '~> 0.10'
 
+  # API docs generation
+  gem 'yard', '~>0.9.9'
+
+  if RUBY_VERSION >= '2.3.0'
+    gem 'yard-junk', '~> 0'
+  end
+
   # Test api
   gem 'rspec', '~> 3.4'
   gem 'fuubar', '~> 2.2.0'

Rakefile

@@ -72,6 +72,13 @@ namespace :lint do
   task :licenses do
     sh 'bundle exec license_finder'
   end
+
+  begin
+    require 'yard-junk/rake'
+    YardJunk::Rake.define_task
+  rescue LoadError
+    warn 'yard-junk requires Ruby 2.3.0. Rake task lint:yard:junk not loaded.'
+  end
 end
 
 namespace :rubygem do

lib/aruba/api/command.rb

@@ -119,16 +119,16 @@ def find_command(commandline)
       # @param [Hash] opts
       #   Options
       #
-      # @option [Integer] exit_timeout
+      # @option opts [Integer] exit_timeout
       #   If the timeout is reached the command will be killed
       #
-      # @option [Integer] io_wait_timeout
+      # @option opts [Integer] io_wait_timeout
       #   Wait for IO to finish
       #
-      # @option [Integer] startup_wait_time
+      # @option opts [Integer] startup_wait_time
       #   Wait for a command to start
       #
-      # @option [String] stop_signal
+      # @option opts [String] stop_signal
       #   Use signal to stop command
       #
       # @yield [SpawnProcess]
@@ -234,13 +234,13 @@ def run_command(*args)
       # @param [Hash] options
       #   Options for aruba
       #
-      # @option [TrueClass,FalseClass] fail_on_error
+      # @option options [Boolean] fail_on_error
       #   Should aruba fail on error?
       #
-      # @option [Integer] exit_timeout
+      # @option options [Integer] exit_timeout
       #   Timeout for execution
       #
-      # @option [Integer] io_wait_timeout
+      # @option options [Integer] io_wait_timeout
       #   Timeout for IO - STDERR, STDOUT
       #
       # rubocop:disable Metrics/CyclomaticComplexity

lib/aruba/api/deprecated.rb

@@ -116,7 +116,7 @@ def eot
       #   The command to by run
       #
       # @see #cmd
-      # @deprectated
+      # @deprecated
       def run_interactive(cmd)
         Aruba.platform.deprecated('The use of "#run_interactive" is deprecated. You can simply use "run" instead')
 
@@ -208,15 +208,11 @@ def check_file_presence(paths, expect_presence = true)
       # @deprecated
       # Check the file size of paths
       #
-      # @params [Hash] paths_and_sizes
+      # @param [Hash] paths_and_sizes
       #   A hash containing the path (key) and the expected size (value)
       #
       # @example
-      #
-      #   paths_and_sizes = {
-      #     'file' => 10
-      #   }
-      #
+      #   paths_and_sizes = { 'file' => 10 }
       #   check_file_size(paths_and_sizes)
       #
       def check_file_size(paths_and_sizes)
@@ -560,7 +556,7 @@ def last_command
       #
       # Full compare arg1 and arg2
       #
-      # @return [TrueClass, FalseClass]
+      # @return [Boolean]
       #   If arg1 is exactly the same as arg2 return true, otherwise false
       def assert_exact_output(expected, actual)
         Aruba.platform.deprecated('The use of "#assert_exact_output" is deprecated. Use "expect(command).to have_output \'exact\'" instead. There are also special matchers for "stdout" and "stderr"')
@@ -573,7 +569,7 @@ def assert_exact_output(expected, actual)
       #
       # Partial compare arg1 and arg2
       #
-      # @return [TrueClass, FalseClass]
+      # @return [Boolean]
       #   If arg2 contains arg1 return true, otherwise false
       def assert_partial_output(expected, actual)
         Aruba.platform.deprecated('The use of "#assert_partial_output" is deprecated. Use "expect(command).to have_output /partial/" instead. There are also special matchers for "stdout" and "stderr"')
@@ -586,7 +582,7 @@ def assert_partial_output(expected, actual)
       #
       # Regex Compare arg1 and arg2
       #
-      # @return [TrueClass, FalseClass]
+      # @return [Boolean]
       #   If arg2 matches arg1 return true, otherwise false
       def assert_matching_output(expected, actual)
         Aruba.platform.deprecated('The use of "#assert_matching_output" is deprecated. Use "expect(command).to have_output /partial/" instead. There are also special matchers for "stdout" and "stderr"')
@@ -599,7 +595,7 @@ def assert_matching_output(expected, actual)
       #
       # Negative regex compare arg1 and arg2
       #
-      # @return [TrueClass, FalseClass]
+      # @return [Boolean]
       #   If arg2 does not match arg1 return true, otherwise false
       def assert_not_matching_output(expected, actual)
         Aruba.platform.deprecated('The use of "#assert_not_matching_output" is deprecated. Use "expect(command).not_to have_output /partial/" instead. There are also special matchers for "stdout" and "stderr"')
@@ -612,7 +608,7 @@ def assert_not_matching_output(expected, actual)
       #
       # Negative partial compare arg1 and arg2
       #
-      # @return [TrueClass, FalseClass]
+      # @return [Boolean]
       #   If arg2 does not match/include arg1 return true, otherwise false
       def assert_no_partial_output(unexpected, actual)
         Aruba.platform.deprecated('The use of "#assert_no_partial_output" is deprecated. Use "expect(command).not_to have_output /partial/" instead. There are also special matchers for "stdout" and "stderr"')
@@ -629,7 +625,7 @@ def assert_no_partial_output(unexpected, actual)
       #
       # Partial compare output of interactive command and arg1
       #
-      # @return [TrueClass, FalseClass]
+      # @return [Boolean]
       #   If output of interactive command includes arg1 return true, otherwise false
       def assert_partial_output_interactive(expected)
         Aruba.platform.deprecated('The use of "#assert_partial_output_interactive" is deprecated. Use "expect(last_command_started).to have_output /partial/" instead. There are also special matchers for "stdout" and "stderr"')
@@ -641,7 +637,7 @@ def assert_partial_output_interactive(expected)
       #
       # Check if command succeeded and if arg1 is included in output
       #
-      # @return [TrueClass, FalseClass]
+      # @return [Boolean]
       #   If exit status is 0 and arg1 is included in output return true, otherwise false
       def assert_passing_with(expected)
         Aruba.platform.deprecated('The use of "#assert_passing_with" is deprecated. Use "expect(all_commands).to all(be_successfully_executed).and include_an_object(have_output(/partial/))" or something similar instead. There are also special matchers for "stdout" and "stderr"')
@@ -654,7 +650,7 @@ def assert_passing_with(expected)
       #
       # Check if command failed and if arg1 is included in output
       #
-      # @return [TrueClass, FalseClass]
+      # @return [Boolean]
       #   If exit status is not equal 0 and arg1 is included in output return true, otherwise false
       def assert_failing_with(expected)
         Aruba.platform.deprecated('The use of "#assert_passing_with" is deprecated. Use "expect(all_commands).not_to include_an_object(be_successfully_executed).and include_an_object(have_output(/partial/))" or something similar instead. There are also special matchers for "stdout" and "stderr"')
@@ -667,7 +663,7 @@ def assert_failing_with(expected)
       #
       # Check exit status of process
       #
-      # @return [TrueClass, FalseClass]
+      # @return [Boolean]
       #   If arg1 is true, return true if command was successful
       #   If arg1 is false, return true if command failed
       def assert_success(success)

lib/aruba/api/environment.rb

@@ -13,6 +13,8 @@ module Environment
       #
       # @param [String] value
       #   The value of the environment variable. Needs to be a string.
+      #
+      # @return [self]
       def set_environment_variable(name, value)
         name = name.to_s
         value = value.to_s
@@ -33,6 +35,8 @@ def set_environment_variable(name, value)
       #
       # @param [String] value
       #   The value of the environment variable. Needs to be a string.
+      #
+      # @return [self]
       def append_environment_variable(name, value)
         name = name.to_s
         value = value.to_s
@@ -53,6 +57,8 @@ def append_environment_variable(name, value)
       #
       # @param [String] value
       #   The value of the environment variable. Needs to be a string.
+      #
+      # @return [self]
       def prepend_environment_variable(name, value)
         name = name.to_s
         value = value.to_s
@@ -68,11 +74,10 @@ def prepend_environment_variable(name, value)
 
       # Remove existing environment variable
       #
-      # @param [String] key
+      # @param [String] name
       #   The name of the environment variable as string, e.g. 'HOME'
       #
-      # @param [String] value
-      #   The value of the environment variable. Needs to be a string.
+      # @return [self]
       def delete_environment_variable(name)
         name = name.to_s
 

lib/aruba/api/filesystem.rb

@@ -40,8 +40,10 @@ def directory?(file)
 
       # Check if file exist and is executable
       #
-      # @param [String] file
-      #   The file which should exist
+      # @param [String] path
+      #   The path which should exist and be executable
+      #
+      # @return [Boolean]
       def executable?(path)
         path = expand_path(path)
 
@@ -50,16 +52,14 @@ def executable?(path)
 
       # Check if path is absolute
       #
-      # @return [TrueClass, FalseClass]
-      #   Result of check
+      # @return [Boolean]
       def absolute?(path)
         ArubaPath.new(path).absolute?
       end
 
       # Check if path is relative
       #
-      # @return [TrueClass, FalseClass]
-      #   Result of check
+      # @return [Boolean]
       def relative?(path)
         ArubaPath.new(path).relative?
       end
@@ -69,7 +69,7 @@ def relative?(path)
       # @return [Array]
       #   List of files and directories
       def all_paths
-        list('.').map { |p| expand_path(p) }
+        list('.').map { |path| expand_path(path) }
       end
 
       # Return all existing files in current directory
@@ -128,10 +128,10 @@ def read(name)
       # The method does not check if file already exists. If the file name is a
       # path the method will create all neccessary directories.
       #
-      # @param [String] file_name
+      # @param [String] name
       #   The name of the file
       #
-      # @param [String] file_content
+      # @param [String] content
       #   The content which should be written to the file
       def write_file(name, content)
         Aruba.platform.create_file(expand_path(name), content, false)
@@ -252,10 +252,10 @@ def move(*args)
       # The method does not check if file already exists. If the file name is a
       # path the method will create all neccessary directories.
       #
-      # @param [String] file_name
+      # @param [String] name
       #   The name of the file
       #
-      # @param [Integer] file_size
+      # @param [Integer] size
       #   The size of the file
       def write_fixed_size_file(name, size)
         Aruba.platform.create_fixed_size_file(expand_path(name), size, false)
@@ -297,8 +297,8 @@ def chmod(*args)
                  mode
                end
 
-        args.each { |p| raise "Expected #{p} to be present" unless exist?(p) }
-        paths = args.map { |p| expand_path(p) }
+        args.each { |path| raise "Expected #{path} to be present" unless exist?(path) }
+        paths = args.map { |path| expand_path(path) }
 
         Aruba.platform.chmod(mode, paths, options)
 
@@ -342,7 +342,7 @@ def remove(*args)
                     {}
                   end
 
-        args = args.map { |p| expand_path(p) }
+        args = args.map { |path| expand_path(path) }
 
         Aruba.platform.rm(args, options)
       end
@@ -370,12 +370,11 @@ def with_file_content(file, &block)
       # @param [Array, Path] paths
       #   The paths
       #
-      # @result [FileSize]
+      # @return [FileSize]
       #   Bytes on disk
-
       def disk_usage(*paths)
         expect(paths.flatten).to Aruba::Matchers.all be_an_existing_path
-        expanded = paths.flatten.map { |p| ArubaPath.new(expand_path(p)) }
+        expanded = paths.flatten.map { |path| ArubaPath.new(expand_path(path)) }
 
         # TODO: change the API so that you could set something like
         # aruba.config.fs_allocation_unit_size directly
@@ -395,6 +394,9 @@ def disk_usage(*paths)
 
       # Get size of file
       #
+      # @param [String] name
+      #   File name
+      #
       # @return [Numeric]
       #   The size of the file
       def file_size(name)

lib/aruba/api/text.rb

@@ -36,9 +36,7 @@ def sanitize_text(text)
         text.chomp
       end
 
-      # @experimental
-      #
-      # Replace variables in command string
+      # Replace variables in command string (experimental)
       #
       # @param [#to_s] text
       #   The text to parse

lib/aruba/aruba_path.rb

@@ -48,8 +48,7 @@ def push(p)
     # @example
     #   path = ArubaPath.new 'path/to/dir.d'
     #   path.pop
-    #   puts path
-    #   # => path/to
+    #   puts path # => path/to
     def pop
       @delegate_sd_obj.pop
     end
@@ -60,9 +59,8 @@ def pop
     #   The count of file name parts
     #
     # @example
-    #
-    # path = ArubaPath.new('path/to/file.txt')
-    # path.depth # => 3
+    #   path = ArubaPath.new('path/to/file.txt')
+    #   path.depth # => 3
     #
     def depth
       __getobj__.each_filename.to_a.size

lib/aruba/hooks.rb

@@ -18,7 +18,7 @@ def initialize
     # @param [String, Symbol] label
     #   The name of the hook
     #
-    # @para [Proc] block
+    # @param [Proc] block
     #   The block which should be run for the hook
     def append(label, block)
       if store.key?(label.to_sym) && store[label.to_sym].respond_to?(:<<)

lib/aruba/matchers/command/be_successfully_executed.rb

@@ -6,7 +6,7 @@
 # @!method be_successfuly_executed
 #   This matchers checks if execution of <command> was successful
 #
-#   @return [TrueClass, FalseClass] The result
+#   @return [Boolean] The result
 #
 #     false:
 #     * if command was not successful

lib/aruba/matchers/command/have_exit_status.rb

@@ -4,7 +4,7 @@
 #   @param [Integer] status
 #     The value of the exit status
 #
-#   @return [TrueClass, FalseClass] The result
+#   @return [Boolean] The result
 #
 #     false:
 #     * if command does not have exit status