Currently all code examples in README.md and data/README.md are executed as part of the gem's test suite (see spec/readme_spec.rb), which doesn't really check their correctness in terms of actually doing what the surrounding text promises, but at least proves that they can be executed without errors (which is important - we love documentation with copy-pastable code examples).
The same kind of "executability check" should be introduced for code examples (only those using the @example annotation) in the gem's YARD documentation.
Where to start: $ grep -r '@example' lib to find occurrences of the @example annotation, then write Ruby code doing the same + extracting the example code. Execute the examples as part of the test suite - analogically to what happens in spec/readme_spec.rb.
Currently all code examples in
README.mdanddata/README.mdare executed as part of the gem's test suite (seespec/readme_spec.rb), which doesn't really check their correctness in terms of actually doing what the surrounding text promises, but at least proves that they can be executed without errors (which is important - we love documentation with copy-pastable code examples).The same kind of "executability check" should be introduced for code examples (only those using the
@exampleannotation) in the gem's YARD documentation.Where to start:
$ grep -r '@example' libto find occurrences of the@exampleannotation, then write Ruby code doing the same + extracting the example code. Execute the examples as part of the test suite - analogically to what happens inspec/readme_spec.rb.