Skip to content

Commit b75938e

Browse files
committed
[DOC] Improve class doc for Coverage
1 parent 23f9a0d commit b75938e

1 file changed

Lines changed: 95 additions & 85 deletions

File tree

ext/coverage/coverage.c

Lines changed: 95 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -480,137 +480,139 @@ rb_coverage_running(VALUE klass)
480480
}
481481

482482
/* \Coverage provides coverage measurement feature for Ruby.
483-
* This feature is experimental, so these APIs may be changed in future.
484483
*
485-
* Caveat: Currently, only process-global coverage measurement is supported.
486-
* You cannot measure per-thread coverage.
484+
* Only process-global coverage measurement is supported, meaning
485+
* that coverage cannot be measure on a per-thread basis.
487486
*
488-
* = Usage
487+
* = Quick Start
489488
*
490-
* 1. require "coverage"
491-
* 2. do Coverage.start
492-
* 3. require or load Ruby source file
493-
* 4. Coverage.result will return a hash that contains filename as key and
494-
* coverage array as value. A coverage array gives, for each line, the
495-
* number of line execution by the interpreter. A +nil+ value means
496-
* coverage is disabled for this line (lines like +else+ and +end+).
489+
* 1. Load coverage using <tt>require "coverage"</tt>.
490+
* 2. Call Coverage.start to set up and begin coverage measurement.
491+
* 3. All Ruby code loaded following the call to Coverage.start will have
492+
* coverage measurement.
493+
* 4. Coverage results can be fetched by calling Coverage.result, which returns a
494+
* hash that contains filenames as the keys and coverage arrays as the values.
495+
* Each element of the coverage array gives the number of times each line was
496+
* executed. A +nil+ value means coverage was disabled for that line (e.g.
497+
* lines like +else+ and +end+).
497498
*
498499
* = Examples
499500
*
500-
* [foo.rb]
501-
* s = 0
502-
* 10.times do |x|
503-
* s += x
504-
* end
501+
* In file +fib.rb+:
505502
*
506-
* if s == 45
507-
* p :ok
508-
* else
509-
* p :ng
503+
* def fibonacci(n)
504+
* if n == 0
505+
* 0
506+
* elsif n == 1
507+
* 1
508+
* else
509+
* fibonacci(n - 1) + fibonacci(n - 2)
510+
* end
510511
* end
511-
* [EOF]
512+
*
513+
* puts fibonacci(10)
514+
*
515+
* In another file, coverage can be measured:
512516
*
513517
* require "coverage"
514518
* Coverage.start
515-
* require "foo.rb"
516-
* p Coverage.result #=> {"foo.rb"=>[1, 1, 10, nil, nil, 1, 1, nil, 0, nil]}
519+
* require "fib.rb"
520+
* Coverage.result # => {"fib.rb" => [1, 177, 34, 143, 55, nil, 88, nil, nil, nil, 1]}
517521
*
518522
* == Lines \Coverage
519523
*
520-
* If a coverage mode is not explicitly specified when starting coverage, lines
521-
* coverage is what will run. It reports the number of line executions for each
522-
* line.
524+
* Lines coverage reports the number of line executions for each line.
525+
* If the coverage mode is not explicitly specified when starting coverage,
526+
* lines coverage is used as the default.
523527
*
524528
* require "coverage"
525529
* Coverage.start(lines: true)
526-
* require "foo.rb"
527-
* p Coverage.result #=> {"foo.rb"=>{:lines=>[1, 1, 10, nil, nil, 1, 1, nil, 0, nil]}}
530+
* require "fib"
531+
* Coverage.result # => {"fib.rb" => {lines: [1, 177, 34, 143, 55, nil, 88, nil, nil, nil, 1]}}
528532
*
529-
* The value of the lines coverage result is an array containing how many times
530-
* each line was executed. Order in this array is important. For example, the
531-
* first item in this array, at index 0, reports how many times line 1 of this
532-
* file was executed while coverage was run (which, in this example, is one
533-
* time).
533+
* The returned hash differs depending on how Coverage.setup or Coverage.start
534+
* was executed.
535+
*
536+
* If Coverage.start or Coverage.setup was called with no arguments, it returns a
537+
* hash which contains filenames as the keys and coverage arrays as the values.
534538
*
535-
* A +nil+ value means coverage is disabled for this line (lines like +else+
536-
* and +end+).
539+
* If Coverage.start or Coverage.setup was called with <tt>line: true</tt>, it
540+
* returns a hash which contains filenames as the keys and hashes as the values.
541+
* The value hash has a key +:lines+ where the value is a coverage array.
542+
*
543+
* Each element of the coverage array gives the number of times the line was
544+
* executed. A +nil+ value in the coverage array means coverage was disabled
545+
* for that line (e.g. lines like +else+ and +end+).
537546
*
538547
* == Oneshot Lines \Coverage
539548
*
540-
* Oneshot lines coverage tracks and reports on the executed lines while
541-
* coverage is running. It will not report how many times a line was executed,
542-
* only that it was executed.
549+
* Oneshot lines coverage is similar to lines coverage, but instead of reporting
550+
* the number of times a line was executed, it only reports the lines that were
551+
* executed.
543552
*
544553
* require "coverage"
545554
* Coverage.start(oneshot_lines: true)
546-
* require "foo.rb"
547-
* p Coverage.result #=> {"foo.rb"=>{:oneshot_lines=>[1, 2, 3, 6, 7]}}
555+
* require "fib"
556+
* Coverage.result # => {"fib.rb" => {oneshot_lines: [1, 11, 2, 4, 7, 5, 3]}}
548557
*
549558
* The value of the oneshot lines coverage result is an array containing the
550559
* line numbers that were executed.
551560
*
552561
* == Branches \Coverage
553562
*
554-
* Branches coverage reports how many times each branch within each conditional
563+
* Branches coverage reports the number of times each branch within each conditional
555564
* was executed.
556565
*
557566
* require "coverage"
558567
* Coverage.start(branches: true)
559-
* require "foo.rb"
560-
* 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}}}}
568+
* require "fib"
569+
* Coverage.result
570+
* # => {"fib.rb" => {
571+
* # branches: {
572+
* # [:if, 0, 2, 2, 8, 5] => {
573+
* # [:then, 1, 3, 4, 3, 5] => 34,
574+
* # [:else, 2, 4, 2, 8, 5] => 143},
575+
* # [:if, 3, 4, 2, 8, 5] => {
576+
* # [:then, 4, 5, 4, 5, 5] => 55,
577+
* # [:else, 5, 7, 4, 7, 39] => 88}}}}
561578
*
562579
* Each entry within the branches hash is a conditional, the value of which is
563-
* another hash where each entry is a branch in that conditional. The values
564-
* are the number of times the method was executed, and the keys are identifying
565-
* information about the branch.
580+
* another hash where each entry is a branch in that conditional. The keys are
581+
* arrays containing information about the branch and the values are the number
582+
* of times the branch was executed.
566583
*
567-
* The information that makes up each key identifying branches or conditionals
568-
* is the following, from left to right:
584+
* The information that makes up the array that are the keys for conditional or
585+
* branches are the following, from left to right:
569586
*
570-
* 1. A label for the type of branch or conditional.
587+
* 1. A label for the type of branch or conditional (e.g. +:if+, +:then+, +:else+).
571588
* 2. A unique identifier.
572-
* 3. The starting line number it appears on in the file.
573-
* 4. The starting column number it appears on in the file.
574-
* 5. The ending line number it appears on in the file.
575-
* 6. The ending column number it appears on in the file.
589+
* 3. Starting line number.
590+
* 4. Starting column number.
591+
* 5. Ending line number.
592+
* 6. Ending column number.
576593
*
577594
* == Methods \Coverage
578595
*
579596
* Methods coverage reports how many times each method was executed.
580597
*
581-
* [foo_method.rb]
582-
* class Greeter
583-
* def greet
584-
* "welcome!"
585-
* end
586-
* end
587-
*
588-
* def hello
589-
* "Hi"
590-
* end
591-
*
592-
* hello()
593-
* Greeter.new.greet()
594-
* [EOF]
595-
*
596598
* require "coverage"
597599
* Coverage.start(methods: true)
598-
* require "foo_method.rb"
599-
* p Coverage.result #=> {"foo_method.rb"=>{:methods=>{[Object, :hello, 7, 0, 9, 3]=>1, [Greeter, :greet, 2, 2, 4, 5]=>1}}}
600+
* require "fib"
601+
* p Coverage.result #=> {"fib.rb" => {methods: {[Object, :fibonacci, 1, 0, 9, 3] => 177}}}
600602
*
601-
* Each entry within the methods hash represents a method. The values in this
602-
* hash are the number of times the method was executed, and the keys are
603+
* Each entry within the methods hash represents a method. The keys are arrays
604+
* containing hash are the number of times the method was executed, and the keys are
603605
* identifying information about the method.
604606
*
605607
* The information that makes up each key identifying a method is the following,
606608
* from left to right:
607609
*
608-
* 1. The class.
609-
* 2. The method name.
610-
* 3. The starting line number the method appears on in the file.
611-
* 4. The starting column number the method appears on in the file.
612-
* 5. The ending line number the method appears on in the file.
613-
* 6. The ending column number the method appears on in the file.
610+
* 1. Class that the method was defined in.
611+
* 2. Method name as a Symbol.
612+
* 3. Starting line number of the method.
613+
* 4. Starting column number of the method.
614+
* 5. Ending line number of the method.
615+
* 6. Ending column number of the method.
614616
*
615617
* == Eval \Coverage
616618
*
@@ -670,16 +672,24 @@ rb_coverage_running(VALUE klass)
670672
*
671673
* == All \Coverage Modes
672674
*
673-
* You can also run all modes of coverage simultaneously with this shortcut.
674-
* Note that running all coverage modes does not run both lines and oneshot
675-
* lines. Those modes cannot be run simultaneously. Lines coverage is run in
676-
* this case, because you can still use it to determine whether or not a line
677-
* was executed.
675+
* All modes of coverage can be enabled simultaneously using the Symbol +:all+.
676+
* However, note that this mode runs lines coverage and not oneshot lines since
677+
* they cannot be ran simultaneously.
678678
*
679679
* require "coverage"
680680
* Coverage.start(:all)
681-
* require "foo.rb"
682-
* 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=>{}}}
681+
* require "fib"
682+
* Coverage.result
683+
* # => {"fib.rb" => {
684+
* # lines: [1, 177, 34, 143, 55, nil, 88, nil, nil, nil, 1],
685+
* # branches: {
686+
* # [:if, 0, 2, 2, 8, 5] => {
687+
* # [:then, 1, 3, 4, 3, 5] => 34,
688+
* # [:else, 2, 4, 2, 8, 5] => 143},
689+
* # [:if, 3, 4, 2, 8, 5] => {
690+
* # [:then, 4, 5, 4, 5, 5] => 55,
691+
* # [:else, 5, 7, 4, 7, 39] => 88}}}},
692+
* # methods: {[Object, :fibonacci, 1, 0, 9, 3] => 177}}}
683693
*/
684694
void
685695
Init_coverage(void)

0 commit comments

Comments
 (0)