1 files changed, 111 insertions, 1 deletions
diff --git a/ext/coverage/coverage.c b/ext/coverage/coverage.c
index be61595163..0af5579ffc 100644
--- a/ext/coverage/coverage.c
+++ b/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)