$30 off During Our Annual Pro Sale. View Details »

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

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

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

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

Alex Rodionov

June 19, 2014
Tweet

More Decks by Alex Rodionov

Other Decks in Technology

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