Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

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

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

D049f551aa71e6326c74002ac8e6788a?s=128

Alex Rodionov

June 19, 2014
Tweet

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
  7. None
  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
  12. None
  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

  15. None
  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
  20. None
  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 ...
  23. None
  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
  27. None
  28. plugins

  29. kraft001/yard-restful

  30. lsegal/yard-spec-plugin

  31. AndrewO/yard-blame

  32. None
  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. ?