Tweet
Tweet

Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

RDoc

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

No content

Slide 8

Slide 8 text

TomDoc

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

No content

Slide 13

Slide 13 text

YARD

Slide 14

Slide 14 text

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


Slide 15

Slide 15 text

No content

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

# @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

Slide 18

Slide 18 text

# @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

Slide 19

Slide 19 text

# @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

Slide 20

Slide 20 text

No content

Slide 21

Slide 21 text

diff

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

No content

Slide 24

Slide 24 text

graph

Slide 25

Slide 25 text

class First ; end
 class Second < First ; end
 class Third < First ; end
 class Fourth < Second ; end


Slide 26

Slide 26 text

$ 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

Slide 27

Slide 27 text

No content

Slide 28

Slide 28 text

plugins

Slide 29

Slide 29 text

kraft001/yard-restful

Slide 30

Slide 30 text

lsegal/yard-spec-plugin

Slide 31

Slide 31 text

AndrewO/yard-blame

Slide 32

Slide 32 text

No content

Slide 33

Slide 33 text

"""
 Adds two numbers.
 
 >>> sum(1, 1)
 2
 >>> sum(1, -1)
 0
 
 Returns sum of two numbers.
 """
 def sum(a, b):
 return a + b
 
 
 
 
 


Slide 34

Slide 34 text

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


Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

doctest

Slide 37

Slide 37 text

tablatom/rubydoctest # doctest:
 # >> sum(1, 1)
 # => 2
 # >> sum(1, -1)
 # => 0
 def sum(a, b)
 a + b
 end

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

p0deje/yard-doctest

Slide 41

Slide 41 text

p0deje/yard-doctest # @example # sum(1, 1) # #=> 2 # # @example # sum(1, -1) # #=> 0
 def sum(a, b)
 a + b
 end

Slide 42

Slide 42 text

p0deje/yard-doctest # ./yard-doctest_helper.rb
 
 require 'example'

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

?