[docs] YARD: avoid warnings and check the docs

[olleolleolle]

This PR improves the YARD documentation annotations.

• fix some typos in directives
• fix some copy and paste errors in names of things
• avoid using p as a local variable name

Found all these using the yard-junk gem.

[maxmeyer]

Are you aware of a tool or have experience using such a tool to test our documentation?

• https://github.com/backus/yardcheck
• https://github.com/rrrene/inch

Does it makes sense to add such a tool to our test suite or at least have an icon in our README? What do you think. Feel free to have a look at some helpful tools and add them to the toolchain. Though I'm not sure, if those tools should make our test suite fail - without a failure adding them to the test suite does not make sense.

[maxmeyer]

Does it makes sense to have Boolean here as well?

[maxmeyer]

There are many more files. Would you like to change it yourself? And change all occurences of [TrueClass, FalseClass] to [Boolean]

• lib/aruba/api/command.rb
• lib/aruba/api/deprecated.rb
• lib/aruba/matchers/command/be_successfully_executed.rb
• lib/aruba/matchers/command/have_exit_status.rb
• lib/aruba/matchers/command/have_finished_in_time.rb
• lib/aruba/matchers/command/have_output.rb
• lib/aruba/matchers/command/have_output_on_stderr.rb
• lib/aruba/matchers/command/have_output_on_stdout.rb
• lib/aruba/matchers/command/have_output_size.rb
• lib/aruba/matchers/directory/be_an_existing_directory.rb
• lib/aruba/matchers/directory/have_sub_directory.rb
• lib/aruba/matchers/file/be_a_command_found_in_path.rb
• lib/aruba/matchers/file/be_an_existing_executable.rb
• lib/aruba/matchers/file/be_an_existing_file.rb
• lib/aruba/matchers/file/have_file_content.rb
• lib/aruba/matchers/file/have_file_size.rb
• lib/aruba/matchers/file/have_same_file_content.rb
• lib/aruba/matchers/path/a_path_matching_pattern.rb
• lib/aruba/matchers/path/be_an_absolute_path.rb
• lib/aruba/matchers/path/be_an_existing_path.rb
• lib/aruba/matchers/path/have_permissions.rb
• lib/aruba/matchers/path/match_path_pattern.rb
• lib/aruba/matchers/rspec_matcher_include_regexp.rb
• lib/aruba/platforms/aruba_file_creator.rb
• lib/aruba/platforms/aruba_fixed_size_file_creator.rb
• lib/aruba/platforms/unix_platform.rb

[olleolleolle]

I made the replacement.

[maxmeyer]

You missed one in lib/aruba/api/command.rb. It's without an " " in between.

[olleolleolle]

Stating the obvious: A CI tool is good as long as users act on the outputs created. If not, it's no use. At the moment, I don't feel it would make things much better quickly.

The benefit of yard-junk is its improvements (clarification, grouping) of the YARD output.

In short: I have no strong opinion on this issue.

[maxmeyer]

Ok. But I helps to have this tool installed in an developer environment to check the docs if she/he feels it's required? Let's add a "Rake" task for that and add the gem to the "development" group in our Gemfile.

[olleolleolle]

@maxmeyer yard-junk ships with a rake task like that.

[maxmeyer]

@olleolleolle Great!

[olleolleolle]

And, if you ever need to add a true or false or nil to a YARD Type list, you can:
http://www.rubydoc.info/gems/yard/file/docs/Tags.md#Literals

[olleolleolle]

@maxmeyer Would you prefer if I added the yard-junk tool as a development dependency in the Gemfile in this PR, or as a separate change?

[maxmeyer]

I think it is ok to add it in this PR in a separate commit.

[olleolleolle]

@maxmeyer Maybe this is a deal-breaker: requires 2.3.0+

https://github.com/zverok/yard-junk/blob/master/yard-junk.gemspec#L14

[maxmeyer]

No problem, we use the RUBY_VERSION at some places. I think using it "again", is not a problem from my side. And it's only tooling.

Gemfile:

  gem 'yard', '~>0.9.9'

  if RUBY_VERSION > '2.3'
    gem 'yard-junk', '~>0.0.2'
  end

Be careful, the documentation in the README is not correct. It's .define_task, not .task.

Rakefile:

if RUBY_VERSION > '2.3'
  require 'yard-junk/rake'
  YardJunk::Rake.define_task
end

[olleolleolle]

Yes, it looks neat.

[maxmeyer]

I think the addition is definitively helpful. 😄 Thanks for raising this issue!

And adding it to CI (in the future) would ensure some kind of a standard + ensures better quality of our documentation which would help our users + us as developers.

[maxmeyer]

I don't like "rescue" lib loading without any action. This might result in a search for a failure. Please output at least a warning. Which then can be found on CI - if we choose to add it to the test pipeline.

[olleolleolle]

I used Kernel#warn, is that acceptable?

[olleolleolle]

@maxmeyer Ah, reminds me: there's a --plugin junk, too. For the yardopts. Hm, perhaps that's also best left not used - we have developers on different Ruby versions.

[maxmeyer]

@olleolleolle Thanks.