0

I would like to extract all the @example code in my YARD documentation. Then I can test them to alert me if they need to be updated.

For example...

# @example
#   obj = Some::Object.new
#   obj.method(1,2,3)
def method(a, b, c)
  ...
end

I would like to receive:

obj = Some::Object.new
obj.method(1,2,3)
Schwern
  • 153,029
  • 25
  • 195
  • 336
  • I'm not aware of an easy method for this. You'll probally have to look at the [`YARD::Registry`](https://github.com/lsegal/yard/blob/e167846322cacdcecb12cbd438aee9e78c6873a2/lib/yard/registry.rb) module and figure out how to repurpose it. – max Dec 02 '22 at 16:32
  • Basically Registry gives you a bunch of [CodeObjects](https://rubydoc.info/gems/yard/YARD/CodeObjects) instances that represent classes, modules and methods and those CodeObject's have a [docstring attribute](https://rubydoc.info/gems/yard/YARD/Docstring) which encapsulates the tags. Something like `obj.docstring.tags(:example)` should give you all the tags for a given object. – max Dec 02 '22 at 17:50
  • YARD and RDoc don't have a direct equivalent to Python docstring testing frameworks for embedding executable tests as documentation. Even assuming you can do this, you'd probably be better off moving your examples to MiniTest or RSpec examples, so that they can function as executable tests and well as documented examples. – Todd A. Jacobs Dec 04 '22 at 20:51
  • @ToddA.Jacobs Can I do this without duplicating the examples? Or are you referring to the "tests as documentation" philosophy where the user is expected to read the tests? – Schwern Dec 04 '22 at 22:46
  • @Schwern When run in documentation mode and written well, RSpec and Cucumber can provide very clear documentation, including actual examples, that are also executable tests. But yes, fundamentally this is different from in-line comments with examples. – Todd A. Jacobs Dec 05 '22 at 02:48

0 Answers0