YARD - больше чем просто документация

Выступление на Omsk Ruby Meetup в июне 2014.

https://plus.google.com/events/ckr08kv70f9svf0n50b70hi2cik

Transcript

1. YARD больше чем просто документация5
2. whoami Алексей Родионов5 Paradev @ Toptal5 5 @p0deje5 github.com/p0deje
3. • RDoc5 • TomDoc5 • YARD Документация
4. class Cat
 Crazy = Class.new(Cat)
 LazyError = Class.new(StandardError)
 
 def play(play_with)
 if play_with.is_a?(String)
 Crazy.new
 else
 raise LazyError, "I'm too lazy to play with #{play_with.inspect}."
 end
 end
 end
5. RDoc
6. class Cat
 Crazy = Class.new(Cat)
 LazyError = Class.new(StandardError)
 # Makes cat play with a string. # # *Examples*: # cat = Cat.new # crazy = cat.play_with('long string') # crazy.class # #=> Cat::Crazy # # *Parameters*: # - +play_with+ - Object to play with # *Returns*: # - crazy cat # *Raises*: # - +Cat::LazyError+ if play_with is not a string def play(play_with)
 if play_with.is_a?(String)
 Crazy.new
 else
 raise LazyError, "I'm too lazy to play with #{play_with.inspect}."
 end
 end
 end
8. TomDoc
9. class Cat
 Crazy = Class.new(Cat)
 LazyError = Class.new(StandardError)
 
 # Public: Makes cat play with a string.
 #
 # play_with - The String to play with
 #
 # Examples
 #
 # cat = Cat.new
 # crazy = cat.play_with('long string')
 # crazy.class
 # #=> Cat::Crazy
 #
 # Raises a Cat::LazyError if play_with is not a string.
 #
 # Returns a Cat::Crazy.
 def play(play_with)
 if play_with.is_a?(String)
 Crazy.new
 else
 raise LazyError, "I'm too lazy to play with #{play_with.inspect}."
 end
 end
 end
10. Не понимает константы WTF
11. class Cat
 # Public: Makes cat play with a string.
 #
 # play_with - The String to play with
 #
 # Examples
 #
 # cat = Cat.new
 # crazy = cat.play_with('long string')
 # crazy.class
 # #=> Cat::Crazy
 #
 # Raises a Cat::LazyError if play_with is not a string.
 #
 # Returns a Cat::Crazy.
 def play(play_with)
 if play_with.is_a?(String)
 Crazy.new
 else
 raise LazyError, "I'm too lazy to play with #{play_with.inspect}."
 end
 end
 end
13. YARD
14. class Cat
 Crazy = Class.new(Cat)
 LazyError = Class.new(StandardError)
 
 # Makes cat play with a string.
 #
 # @example
 # cat = Cat.new
 # crazy = cat.play_with('long string')
 # crazy.class
 # #=> Cat::Crazy
 #
 # @param [String] play_with to play with
 # @raise [Cat::LazyError] if play_with is not a string
 # @return [Cat::Crazy] crazy cat
 def play(play_with)
 if play_with.is_a?(String)
 Crazy.new
 else
 raise LazyError, "I'm too lazy to play with #{play_with.inspect}."
 end
 end
 end

16. $ bin/yard doc examples/rdoc.rb $ bin/yard doc —-plugin tomdoc examples/tomdoc.rb
17. # @macro [attach] attribute
 # @method $2
 # @return [$1] value of $3 property
 def attribute(type, method, attr)
 typed_attributes[type] << [method, attr]
 define_attribute(type, method, attr)
 end
18. # @macro [attach] attribute
 # @method $2
 # @return [$1] value of $3 property
 def attribute(type, method, attr)
 typed_attributes[type] << [method, attr]
 define_attribute(type, method, attr)
 end class Anchor
 attribute String, :rel_list, :relList
 end
19. # @macro [attach] attribute
 # @method $2
 # @return [$1] value of $3 property
 def attribute(type, method, attr)
 typed_attributes[type] << [method, attr]
 define_attribute(type, method, attr)
 end class Anchor
 attribute String, :rel_list, :relList
 end
21. diff
22. $ bin/yard diff rack-1.1.0 rack-1.2.1 5 Added objects: 5 Rack::ETag#digest_body (lib/rack/etag.rb:22) Rack::Handler::WEBrick.shutdown (lib/rack/handler/webrick.rb:16) Rack::Lint#verify_content_length (lib/rack/lint.rb:495) Rack::Recursive#_call (lib/rack/recursive.rb:41) 5 ...
24. graph
25. class First ; end
 class Second < First ; end
 class Third < First ; end
 class Fourth < Second ; end

26. $ bin/yard doc examples/graph.rb $ bin/yard graph --dependencies --empty-mixins --full --dot --file graph.dot $ dot -T pdf -o diagram.pdf graph.dot $ open diagram.pdf
28. plugins
29. kraft001/yard-restful
30. lsegal/yard-spec-plugin
31. AndrewO/yard-blame
33. """
 Adds two numbers.
 
 >>> sum(1, 1)
 2
 >>> sum(1, -1)
 0
 
 Returns sum of two numbers.
 """
 def sum(a, b):
 return a + b
 
 
 
 
 

34. """
 Adds two numbers.
 
 >>> sum(1, 1)
 2
 >>> sum(1, -1)
 0
 
 Returns sum of two numbers.
 """
 def sum(a, b):
 return a + b
 
 
 if __name__ == "__main__":
 import doctest
 doctest.testmod()

35. $ python example.py -v 5 Trying: sum(1, 1) Expecting: 2 ok Trying: sum(1, -1) Expecting: 0 ok 1 items had no tests: __main__.sum 1 items passed all tests: 2 tests in __main__ 2 tests in 2 items. 2 passed and 0 failed. Test passed.
36. doctest
37. tablatom/rubydoctest # doctest:
 # >> sum(1, 1)
 # => 2
 # >> sum(1, -1)
 # => 0
 def sum(a, b)
 a + b
 end
38. tablatom/rubydoctest $ gem install rubydoctest $ rubydoctest example.rb 5 === Testing 'example.rb'... 1. OK | 2 comparisons, 1 doctests, 0 failures, 0 errors
39. AndrewO/yard-doctest Так и не был закончен :(
40. p0deje/yard-doctest
41. p0deje/yard-doctest # @example # sum(1, 1) # #=> 2 # # @example # sum(1, -1) # #=> 0
 def sum(a, b)
 a + b
 end
42. p0deje/yard-doctest # ./yard-doctest_helper.rb
 
 require 'example'
43. p0deje/yard-doctest $ bin/yard doctest example.rb 5 Run options: --seed 53035 5 # Running: 5 .. 5 Finished in 0.002210s, 904.9774 runs/s, 904.9774 assertions/s. 5 2 runs, 2 assertions, 0 failures, 0 errors, 0 skips
44. p0deje/yard-doctest $ bin/yard doctest example.rb 5 # Running: 5 .F 5 Finished in 0.027398s, 72.9980 runs/s, 72.9980 assertions/s. 5 1) Failure: #sum#test_0001_ [example.rb:8]: Expected: 3 Actual: 2 5 2 runs, 2 assertions, 1 failures, 0 errors, 0 skips
45. p0deje/yard-doctest - Парсит текст example тэга - Получает из текста expected, actual - Генерирует Minitest::Spec классы - Все остальное делает Minitest
46. p0deje/yard-doctest - Хуки (before/after/after_run) - Шаринг контекстов (и биндингов) - Сколько угодно ассертов в одном example - Rake таск для вас
47. https://github.com/watir/watir-webdriver/pull/264 $ rake yard:doctest 5 Run options: --seed 64595 5 # Running: 5 .......................................... 5 Finished in 208.747670s, 0.2012 runs/s, 0.0623 assertions/s. 5 42 runs, 13 assertions, 0 failures, 0 errors, 0 skips
48. https://github.com/p0deje/yard-doctest
49. ?