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

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

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

Transcript

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

   View Slide

2. whoami
   Алексей Родионов5
   Paradev @ Toptal5
   5
   @p0deje5
   github.com/p0deje
   

   View Slide

3. • RDoc5
   • TomDoc5
   • YARD
   Документация
   

   View Slide

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
   

   View Slide

5. RDoc
   

   View Slide

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
   

   View Slide

7. View Slide

8. TomDoc
   

   View Slide

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
   

   View Slide

10. Не понимает константы
    WTF
    

    View Slide

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
    

    View Slide

12. View Slide

13. YARD
    

    View Slide

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

    

    View Slide

15. View Slide

16. $ bin/yard doc examples/rdoc.rb
    $ bin/yard doc —-plugin tomdoc examples/tomdoc.rb
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

20. View Slide

21. diff
    

    View Slide

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

    View Slide

23. View Slide

24. graph
    

    View Slide

25. class First ; end

    class Second < First ; end

    class Third < First ; end

    class Fourth < Second ; end

    

    View Slide

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
    

    View Slide

27. View Slide

28. plugins
    

    View Slide

29. kraft001/yard-restful
    

    View Slide

30. lsegal/yard-spec-plugin
    

    View Slide

31. AndrewO/yard-blame
    

    View Slide

32. View Slide

33. """

    Adds two numbers.

    

    >>> sum(1, 1)

    2

    >>> sum(1, -1)

    0

    

    Returns sum of two numbers.

    """

    def sum(a, b):

    return a + b

    

    

    

    

    

    

    View Slide

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()

    

    View Slide

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.
    

    View Slide

36. doctest
    

    View Slide

37. tablatom/rubydoctest
    # doctest:

    # >> sum(1, 1)

    # => 2

    # >> sum(1, -1)

    # => 0

    def sum(a, b)

    a + b

    end
    

    View Slide

38. tablatom/rubydoctest
    $ gem install rubydoctest
    $ rubydoctest example.rb
    5
    === Testing 'example.rb'...
    1. OK |
    2 comparisons, 1 doctests, 0 failures, 0 errors
    

    View Slide

39. AndrewO/yard-doctest
    Так и не был закончен :(
    

    View Slide

40. p0deje/yard-doctest
    

    View Slide

41. p0deje/yard-doctest
    # @example
    # sum(1, 1)
    # #=> 2
    #
    # @example
    # sum(1, -1)
    # #=> 0

    def sum(a, b)

    a + b

    end
    

    View Slide

42. p0deje/yard-doctest
    # ./yard-doctest_helper.rb

    

    require 'example'
    

    View Slide

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
    

    View Slide

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
    

    View Slide

45. p0deje/yard-doctest
    - Парсит текст example тэга
    - Получает из текста expected, actual
    - Генерирует Minitest::Spec классы
    - Все остальное делает Minitest
    

    View Slide

46. p0deje/yard-doctest
    - Хуки (before/after/after_run)
    - Шаринг контекстов (и биндингов)
    - Сколько угодно ассертов в одном example
    - Rake таск для вас
    

    View Slide

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
    

    View Slide

48. https://github.com/p0deje/yard-doctest
    

    View Slide

49. ?
    

    View Slide