How to document simple scripts with YARD?

Question

I am interested in documenting my code, the majority of which are scripts where I do not create new classes.

From reading the YARD docs, and trying to actually implement some YARD documentation, it seems that you declare your YARD tags within a defined class. I have successfully used YARD when I create a class or add new methods to a class, as in the sample code below, and I have also been able to document simple things using YARD tags like @author and @example.

#!/usr/bin/env ruby -wKU

## a YARD test

class String

  # 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   

end

My questions are:

1. Is there a way to use YARD tags to document code (especially methods) without defining classes?
2. If not, what solutions exist other than putting extensive comments in my code?

Answer 1

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.