Adding Type Signatures into Ruby Docs

Since Ruby's beginnings, its documentation has been maintained by people who help and support the language. Before the core team releases a new version of Ruby, contributors must update the documentation to reflect the current set of functionality, which presents many challenges to remaining consistent over Ruby's long history. One method may describe a set of arguments and the types one way, but another may tell them differently. Ruby 3 gained a highly requested feature, Type Annotations! A way to describe the structure of your Ruby Programs. In this talk, we'll look at improving Ruby's documentation by leveraging Ruby's Type Signatures to provide users with more accurate and consistent documentation.

Transcript

4. RDoc orders search results alphabetically
5. to_s
6. to_s • ARGF • Addrinfo • Array • Benchmark::Tms Alphabetical Order
7. to_s • Integer • Float • BigDecimal • Object Core Class Order • ARGF • Addrinfo • Array • Benchmark::Tms Alphabetical Order
8. I wanted to build something that understands Ruby-src docs
9. rubyapi.org
10. Supports Ruby 2.3 to 3.1
11. Quick Search & Autocomplete
12. 80K visitors, 100K+ page views/month
13. View source code inline or on Github
14. Execute code blocks with Ruby REPL
16. How can I help improve Ruby documentation?
17. Adding Type Signatures into Ruby Docs
18. Colby Swandale @oceanicpanda
25. Call Sequences Type Signatures
26. RDoc Ruby standard documentation library
27. github.com/ruby/rdoc
28. module Rake ## # A Task is the basic unit of work in a Rakefile. Tasks have associated # actions (possibly more than one) and a list of prerequisites. When # invoked, a task will first ensure that all of its prerequisites have an # opportunity to run and then it will execute its own actions. # # Tasks are not usually created directly using the new method, but rather # use the +file+ and +task+ convenience methods. # class Task # Create a task named +task_name+ with no actions or prerequisites. Use # +enhance+ to add actions and prerequisites. def initialize(task_name, app) ... end end end
29. = Bug Triaging Guide This guide discusses recommendations for triaging bugs in Ruby's bug tracker. == Bugs with Reproducible Examples These are the best bug reports. First, consider whether the bug reported is actually an issue or if it is expected Ruby behavior. If it is expected Ruby behavior, update the issue with why the behavior is expected, and set the status to Rejected. bug_triaging.rdoc
30. $ rdoc . Parsing sources... 100% [22/22] test/stringio/test_stringio.rb Generating Darkfish format into /Users/colby/Github/stringio/doc... Files: 22 Total: 236 (163 undocumented) 30.93% documented Elapsed: 0.3s
32. $ rdoc . —format pot Parsing sources... 100% [897/897] yjit.c Generating POT format into /Users/colby/Github/ruby/docs... Files: 897 Total: 12129 (2858 undocumented) 76.44% documented Elapsed: 29.7s
33. $ rdoc . —format pot Do you know what this format is?
36. require 'rdoc' @rdoc = RDoc::RDoc.new @rdoc_options = RDoc::Options.load_options.tap |r| r.files = Dir[Dir.pwd] r.template = "rdoc" r.quiet = true end @rdoc.document @rdoc_options
37. /* * call-seq: * empty? -> true or false * * Returns +true+ if the length of +self+ is zero, +false+ otherwise: * * "hello".empty? # => false * " ".empty? # => false * "".empty? # => true * */ static VALUE rb_str_empty(VALUE str) { return RBOOL(RSTRING_LEN(str) == 0); }
38. /* * call-seq: * empty? -> true or false * * Returns +true+ if the length of +self+ is zero, +false+ otherwise: * * "hello".empty? # => false * " ".empty? # => false * "".empty? # => true * */ static VALUE rb_str_empty(VALUE str) { return RBOOL(RSTRING_LEN(str) == 0); } Description Call Sequence
41. Challenge to keep call sequences consistent
42. str[integer] = new_str str[integer, integer] = new_str str[range] = aString str[regexp] = new_str str[regexp, integer] = new_str str[regexp, name] = new_str str[other_str] = new_str String#[]
43. str[integer] = new_str str[integer, integer] = new_str str[range] = aString str[regexp] = new_str str[regexp, integer] = new_str str[regexp, name] = new_str str[other_str] = new_str String#[]
44. str[integer] = new_str str[integer, integer] = new_str str[range] = aString str[regexp] = new_str str[regexp, integer] = new_str str[regexp, name] = new_str str[other_str] = new_str String#[]
45. str[integer] = new_str str[integer, integer] = new_str str[range] = aString str[regexp] = new_str str[regexp, integer] = new_str str[regexp, name] = new_str str[other_str] = new_str Call sequences are plain text
46. Can we automatically generate method sequences?
47. Yes! 🎉
48. RBS Type Signatures for Ruby
49. github.com/ruby/rbs
50. # string.rbs class String include Comparable # https://github.com/ruby/rbs/blob/master/core/string.rbs # Returns a new String containing `other_string` # concatenated to `self`: # # "Hello from " + self.to_s # => "Hello from main” def +: (string other_str) -> String end
51. class String include Comparable def gsub: (Regexp | string pattern, string replacement) -> String | (Regexp | string pattern, Hash[String, String] hash) -> String | (Regexp | string pattern) { (String match) -> _ToS } -> String | (Regexp | string pattern) -> ::Enumerator[String, self] end
52. Create your own RBS f iles
53. # lib/application.rb class Application def hello(name) "Hello, #{name}!" end end
54. # main.rb require_relative ‘./lib/application app = Application.new app.hello(“Colby”)
55. $ rbs prototype rb lib/application.rb class Application def hello: (untyped name) -> ::String end
56. $ rbs prototype rb lib/application.rb class Application def hello: (untyped name) -> ::String end
57. $ rbs prototype rb lib/application.rb class Application def hello: (String name) -> ::String end
58. # sig/lib/application.rbs class Application def hello: (String name) -> ::String end
59. # Gemfile source "https://rubygems.org" gem "steep"
60. # Steepfile target :lib do check "lib" check "main.rb" signature "sig" end
61. $ bundle exec steep check .....................................................................
62. # main.rb require_relative ‘./lib/application app = Application.new app.hello(1)
63. $ bundle exec steep check .....................................................................F main.rb:4:15: [error] Cannot pass a value of type `::Integer` as an argument of type `::String` ! ::Integer <: ::String ! ::Numeric <: ::String ! ::Object <: ::String ! ::BasicObject <: ::String ! ! Diagnostic ID: Ruby::ArgumentTypeMismatch ! " puts app.hello(1)
64. $ ruby main.rb Hello, 1!
66. Ruby API doesn’t support RBI at the moment
67. 😮💨
68. Call Sequences Type Signatures
69. $ ./bin/rake import:ruby[3.1.2]
70. def prepare_environment system "unzip #{ruby_src_download_path}” if release.has_type_signatures? system "gem unpack --target #{download_path.join("gems")} “ \ “#{download_path.join(“gems/rbs-*.gem”)}" end end
71. def prepare_environment system "unzip #{ruby_src_download_path}” if release.has_type_signatures? system "gem unpack --target #{download_path.join("gems")} “ \ “#{download_path.join(“gems/rbs-*.gem”)}" end end
72. def prepare_environment system "unzip #{ruby_src_download_path}” if release.has_type_signatures? system "gem unpack --target #{download_path.join("gems")} “ \ “#{download_path.join(“gems/rbs-*.gem”)}" end end
73. def prepare_environment system "unzip #{ruby_src_download_path}” if release.has_type_signatures? system "gem unpack --target #{download_path.join("gems")} “ \ “#{download_path.join(“gems/rbs-*.gem”)}" end end
74. if @release.has_type_signatures? require_relative "./ruby_type_signature_repository" @type_repository = RubyTypeSignatureRepository .new(<path-to-rbs-gem>) end
75. if @release.has_type_signatures? require_relative "./ruby_type_signature_repository" @type_repository = RubyTypeSignatureRepository .new(<path-to-rbs-gem>) end
76. @repository ||= RBS::Repository.new(no_stdlib: true).tap do |r| r.add(rbs_gem_path.join("stdlib")) end @loader = RBS::EnvironmentLoader .new(core_root: rbs_gem_path.join(CORE_PATH)) @environment = RBS::Environment.from_loader(@loader).resolve_type_names @builder = RBS::DefinitionBuilder.new(env: @environment) Setup RBS environment
77. @repository ||= RBS::Repository.new(no_stdlib: true).tap do |r| r.add(rbs_gem_path.join("stdlib")) end @loader = RBS::EnvironmentLoader .new(core_root: rbs_gem_path.join(CORE_PATH)) @environment = RBS::Environment.from_loader(@loader).resolve_type_names @builder = RBS::DefinitionBuilder.new(env: @environment) Setup RBS environment
78. @repository ||= RBS::Repository.new(no_stdlib: true).tap do |r| r.add(rbs_gem_path.join("stdlib")) end @loader = RBS::EnvironmentLoader .new(core_root: rbs_gem_path.join(CORE_PATH)) @environment = RBS::Environment.from_loader(@loader).resolve_type_names @builder = RBS::DefinitionBuilder.new(env: @environment) Setup RBS environment
79. @repository ||= RBS::Repository.new(no_stdlib: true).tap do |r| r.add(rbs_gem_path.join("stdlib")) end @loader = RBS::EnvironmentLoader .new(core_root: rbs_gem_path.join(CORE_PATH)) @environment = RBS::Environment.from_loader(@loader).resolve_type_names @builder = RBS::DefinitionBuilder.new(env: @environment) Setup RBS environment
80. if method_rdoc.type == “instance" @type_repository.signature_for_object_instance_method( object: object_rdoc.name, method: method_doc.name )&.map(&:to_s) elsif method_rdoc.type == “class" @type_repository.signature_for_object_class_method( object: object_rdoc.name, method: method_rdoc.name )&.map(&:to_s) end Fetching a method’s signatures
81. method_type = RBS::TypeName.new( name: “String”, namespace: RBS::Namespace.root ) // instance methods @builder.build_instance(method_type).methods[:to_i] &.method_types // class methods @builder.build_singleton(method_type).methods[:to_i] &.method_types Query RBS for type signature
82. Type Signatures also have their own challenges
83. Managed separately from ruby-src
84. Not optimised for humans
85. String#gsub (::Regexp | ::string pattern, ::string replacement) -> ::String (::Regexp | ::string pattern, ::Hash[::String, ::String] hash) -> ::String (::Regexp | ::string pattern) { (::String match) -> ::_ToS } -> ::String (::Regexp | ::string pattern) -> ::Enumerator[::String, self] Example
86. String#gsub (::Regexp | ::string pattern, ::string replacement) -> ::String (::Regexp | ::string pattern, ::Hash[::String, ::String] hash) -> ::String (::Regexp | ::string pattern) { (::String match) -> ::_ToS } -> ::String (::Regexp | ::string pattern) -> ::Enumerator[::String, self] Example
87. Optimised for computers humans
88. (::int index) -> ::String? (::int start, ::int length) -> ::String? (::Range[::Integer] | ::Range[::Integer?] range) -> ::String? (::Regexp regexp) -> ::String? (::Regexp regexp, ::int | ::String capture) -> ::String? (::String match_str) -> ::String?
89. (int index) -> String? (int start, int length) -> String? (Range[Integer] | Range[Integer?] range) -> String? (Regexp regexp) -> String? (Regexp regexp, int | String capture) -> String? (String match_str) -> String?
90. (int index) -> String? (int start, int length) -> String? (Range[Integer] | Range[Integer?] range) -> String? (Regexp regexp) -> String? (Regexp regexp, int | String capture) -> String? (String match_str) -> String?
91. (Integer index) -> String? (Integer start, Integer length) -> String? (Range[Integer] | Range[Integer?] range) -> String? (Regexp regexp) -> String? (Regexp regexp, Integer | String capture) -> String? (String match_str) -> String?
92. Integer index -> String? Integer start, Integer length -> String? Range[Integer] | Range[Integer?] range -> String? Regexp regexp -> String? Regexp regexp, Integer | String capture -> String? String match_str -> String?
93. Integer index -> String? Integer start, Integer length -> String? Range[Integer] | Range[Integer?] range -> String? Regexp regexp -> String? Regexp regexp, Integer | String capture -> String? String match_str -> String?
94. Range[Integer] | Range[Integer?] range -> String?
95. (::int index) -> ::String? (::int start, ::int length) -> ::String? (::Range[::Integer] | ::Range[::Integer?] range) -> ::String? (::Regexp regexp) -> ::String? (::Regexp regexp, ::int | ::String capture) -> ::String? (::String match_str) -> ::String? Integer index -> String? Integer start, Integer length -> String? Range[Integer] | Range[Integer?] range -> String? Regexp regexp -> String? Regexp regexp, Integer | String capture) -> String? String match_str -> String?
96. Next steps
97. github.com/rubyapi/rubyapi
98. Checkout the other talks about Ruby Types! Types teaches success, what will we do? - @fugakkbn Let's collect type info during Ruby running and automaticall - @pink_bangbi Ruby programming with types in action - @soutaro
99. ありがとう