How to Document Ruby Code

How to document Ruby code?

You should target your documentation for the RDoc processor, which can find your documentation and generate HTML from it. You've put your comment in the right place for that, but you should have a look at the RDoc documentation to learn about the kinds of tags that RDoc knows how to format. To that end, I'd reformat your comment as follows:

  # Runs a subprocess and applies handlers for stdout and stderr
  # Params:
  # +command+:: command line string to be executed by the system
  # +outhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil)
  # +errhandler+:: +Proc+ object that takes a pipe object as first and only param (may be nil)

How to document Ruby code using Doxygen?

Short answer, no. Long answer, still no. Doxygen will come to Ruby eventually, but I don't have the sense that it's going to happen any time soon. In the short term, you're stuck with either RDoc or YARD.

How to document simple scripts with YARD?

Just document the methods in the script as you would for any class- or module-based methods. YARD should document them as part of the "Top Level Namespace".

The following modification to your script just works, removing the class String wrapper:

#!/usr/bin/env ruby -wKU

# Prints a string using two supplied strings
#
# @param str1 [String] A string to print
# @param str2 [String] A string to print
# @return [String] A printed string
def yardTest(str1, str2)
  p sprintf("Hello, %s, %s", str1, str2)
end

You might also want to consider documenting the API of the script for its users, which is for a different purpose and audience of course.

Also do consider separating the command-line interface from the methods that perform actions - in which case you will end up creating suitable modules and classes. This is a natural pattern when making anything remotely complicated, and would allow you to share your logic between scripts in future, or perhaps into things that are not invoked from the command line. You could take a look at the thor gem - it is a framework for creating command-line scripts, and includes examples of command-line interfaces that follow a nice pattern of abstraction. Thor has support for easily including standard practice usage and help in a command-line script.

Documenting Ruby code results within source file

You need to use the t9md / vim-ruby-xmpfilter. Look also the README section.

You need to have rcodetools gem mandatory.

After that go though the issue, I logged.

What's the most official documentation of or way to learn Ruby's syntax?

The canonical documentation of Ruby's syntax is maintained along with with language's source code in the doc/syntax directory. You can read it on GitHub or e.g. on ruby-doc.org.

There, you will find the description of the &. operator:

You may use &. to designate a receiver, then my_method is not invoked and the result is nil when the receiver is nil. In that case, the arguments of my_method are not evaluated.

as well as the logic to convert a Proc object (or more correctly: an object which can be converted to a Proc) to a block:

You can convert a proc or lambda to a block argument with the & operator:
argument = proc { |a| puts "#{a.inspect} was yielded" }

my_method(&argument)

Here, the interesting thing to note is that Symbols respond to to_proc which allows Symbols to act like procs (and thus can be converted to a proc and subsequently to a block when used to call a method with e.g. my_method(&:foo).

In general, to learn about Ruby's syntax and approach to programming, you could start with one of several books, e.g. Programming Ruby 1.9 and 2.0. In general, books tend to take some time (usually a few years) from start to publishing and thus tend to not cover the very latest language additions. However, they can give you a good overview about the language and its core concepts.

There are some additions in newer versions of Ruby which make some things easier, like the &. operator added in Ruby 2.3 or things like default frozen strings. While these additions are useful, you will usually stumble upon them when you start to actually programming in Ruby. Here, it might then be useful to follow the release news where new features and notable changes are briefly described.