Document Different Coverage Modes

This commits adds in documentation to illustrate the different modes you
can start coverage with. Examples are provided to show how to start each
of these modes, along with an explanation of the mode and a description
of the output.

ext/coverage/coverage.c

@@ -346,7 +346,7 @@ rb_coverage_running(VALUE klass)
  *    number of line execution by the interpreter. A +nil+ value means
  *    coverage is disabled for this line (lines like +else+ and +end+).
  *
- * = Example
+ * = Examples
  *
  *   [foo.rb]
  *   s = 0
@@ -365,6 +365,116 @@ rb_coverage_running(VALUE klass)
  *   Coverage.start
  *   require "foo.rb"
  *   p Coverage.result  #=> {"foo.rb"=>[1, 1, 10, nil, nil, 1, 1, nil, 0, nil]}
+ *
+ * == Lines Coverage
+ *
+ * If a coverage mode is not explicitly specified when starting coverage, lines
+ * coverage is what will run. It reports the number of line executions for each
+ * line.
+ *
+ *   require "coverage"
+ *   Coverage.start(lines: true)
+ *   require "foo.rb"
+ *   p Coverage.result #=> {"foo.rb"=>{:lines=>[1, 1, 10, nil, nil, 1, 1, nil, 0, nil]}}
+ *
+ * The value of the lines coverage result is an array containing how many times
+ * each line was executed. Order in this array is important. For example, the
+ * first item in this array, at index 0, reports how many times line 1 of this
+ * file was executed while coverage was run (which, in this example, is one
+ * time).
+ *
+ * A +nil+ value means coverage is disabled for this line (lines like +else+
+ * and +end+).
+ *
+ * == Oneshot Lines Coverage
+ *
+ * Oneshot lines coverage tracks and reports on the executed lines while
+ * coverage is running. It will not report how many times a line was executed,
+ * only that it was executed.
+ *
+ *   require "coverage"
+ *   Coverage.start(oneshot_lines: true)
+ *   require "foo.rb"
+ *   p Coverage.result #=> {"foo.rb"=>{:oneshot_lines=>[1, 2, 3, 6, 7]}}
+ *
+ * The value of the oneshot lines coverage result is an array containing the
+ * line numbers that were executed.
+ *
+ * == Branches Coverage
+ *
+ * Branches coverage reports how many times each branch within each conditional
+ * was executed.
+ *
+ *   require "coverage"
+ *   Coverage.start(branches: true)
+ *   require "foo.rb"
+ *   p Coverage.result #=> {"foo.rb"=>{:branches=>{[:if, 0, 6, 0, 10, 3]=>{[:then, 1, 7, 2, 7, 7]=>1, [:else, 2, 9, 2, 9, 7]=>0}}}}
+ *
+ * Each entry within the branches hash is a conditional, the value of which is
+ * another hash where each entry is a branch in that conditional. The values
+ * are the number of times the method was executed, and the keys are identifying
+ * information about the branch.
+ *
+ * The information that makes up each key identifying branches or conditionals
+ * is the following, from left to right:
+ *
+ * 1. A label for the type of branch or conditional.
+ * 2. A unique identifier.
+ * 3. The starting line number it appears on in the file.
+ * 4. The starting column number it appears on in the file.
+ * 5. The ending line number it appears on in the file.
+ * 6. The ending column number it appears on in the file.
+ *
+ * == Methods Coverage
+ *
+ * Methods coverage reports how many times each method was executed.
+ *
+ *   [foo_method.rb]
+ *   class Greeter
+ *     def greet
+ *       "welcome!"
+ *     end
+ *   end
+ *
+ *   def hello
+ *     "Hi"
+ *   end
+ *
+ *   hello()
+ *   Greeter.new.greet()
+ *   [EOF]
+ *
+ *   require "coverage"
+ *   Coverage.start(methods: true)
+ *   require "foo_method.rb"
+ *   p Coverage.result #=> {"foo_method.rb"=>{:methods=>{[Object, :hello, 7, 0, 9, 3]=>1, [Greeter, :greet, 2, 2, 4, 5]=>1}}}
+ *
+ * Each entry within the methods hash represents a method. The values in this
+ * hash are the number of times the method was executed, and the keys are
+ * identifying information about the method.
+ *
+ * The information that makes up each key identifying a method is the following,
+ * from left to right:
+ *
+ * 1. The class.
+ * 2. The method name.
+ * 3. The starting line number the method appears on in the file.
+ * 4. The starting column number the method appears on in the file.
+ * 5. The ending line number the method appears on in the file.
+ * 6. The ending column number the method appears on in the file.
+ *
+ * == All Coverage Modes
+ *
+ * You can also run all modes of coverage simultaneously with this shortcut.
+ * Note that running all coverage modes does not run both lines and oneshot
+ * lines. Those modes cannot be run simultaneously. Lines coverage is run in
+ * this case, because you can still use it to determine whether or not a line
+ * was executed.
+ *
+ *   require "coverage"
+ *   Coverage.start(:all)
+ *   require "foo.rb"
+ *   p Coverage.result #=> {"foo.rb"=>{:lines=>[1, 1, 10, nil, nil, 1, 1, nil, 0, nil], :branches=>{[:if, 0, 6, 0, 10, 3]=>{[:then, 1, 7, 2, 7, 7]=>1, [:else, 2, 9, 2, 9, 7]=>0}}, :methods=>{}}}
  */
 void
 Init_coverage(void)