rbs 2.0.0 → 2.1.0

data/core/trace_point.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=trace_point.rb -->
 # Document-class: TracePoint
 #
 # A class that provides the functionality of Kernel#set_trace_func in a nice
@@ -30,7 +31,7 @@
 # To filter what is traced, you can pass any of the following as `events`:
 #
 # `:line`
-# :   execute code on a new line
+# :   execute an expression or statement on a new line
 # `:class`
 # :   start a class or module definition
 # `:end`
@@ -49,6 +50,10 @@
 # :   event hook at block entry
 # `:b_return`
 # :   event hook at block ending
+# `:a_call`
+# :   event hook at all calls (`call`, `b_call`, and `c_call`)
+# `:a_return`
+# :   event hook at all returns (`return`, `b_return`, and `c_return`)
 # `:thread_begin`
 # :   event hook at thread beginning
 # `:thread_end`
@@ -58,8 +63,11 @@
 # `:script_compiled`
 # :   new Ruby code compiled (with `eval`, `load` or `require`)
 #
-#
 class TracePoint < Object
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - TracePoint.new(*events) { |obj| block }         -> obj
+  # -->
   # Returns a new TracePoint object, not enabled by default.
   #
   # Next, in order to activate the trace, you must use TracePoint#enable
@@ -104,6 +112,24 @@ class TracePoint < Object
   #
   def initialize: (*Symbol events) { (TracePoint tp) -> void } -> void
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - TracePoint.allow_reentry
+  # -->
+  # In general, while a TracePoint callback is running, other registered callbacks
+  # are not called to avoid confusion by reentrance. This method allows the
+  # reentrance in a given block. This method should be used carefully, otherwise
+  # the callback can be easily called infinitely.
+  #
+  # If this method is called when the reentrance is already allowed, it raises a
+  # RuntimeError.
+  #
+  def self.allow_reentry: () { () -> void } -> void
+
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - TracePoint.stat -> obj
+  # -->
   # Returns internal information of TracePoint.
   #
   # The contents of the returned value are implementation specific. It may be
@@ -113,26 +139,44 @@ class TracePoint < Object
   #
   def self.stat: () -> untyped
 
-  # Document-method: trace
-  #
-  #     A convenience method for TracePoint.new, that activates the trace
-  #     automatically.
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - TracePoint.trace(*events) { |obj| block }        -> obj
+  # -->
+  # A convenience method for TracePoint.new, that activates the trace
+  # automatically.
   #
-  #            trace = TracePoint.trace(:call) { |tp| [tp.lineno, tp.event] }
-  #            #=> #<TracePoint:enabled>
+  #     trace = TracePoint.trace(:call) { |tp| [tp.lineno, tp.event] }
+  #     #=> #<TracePoint:enabled>
   #
-  #            trace.enabled? #=> true
+  #     trace.enabled? #=> true
   #
   def self.trace: (*Symbol events) { (TracePoint tp) -> void } -> TracePoint
 
-  # Return the generated binding object from event
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - binding()
+  # -->
+  # Return the generated binding object from event.
+  #
+  # Note that for `c_call` and `c_return` events, the binding returned is the
+  # binding of the nearest Ruby method calling the C method, since C methods
+  # themselves do not have bindings.
   #
   def binding: () -> Binding
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - callee_id()
+  # -->
   # Return the called name of the method being called
   #
   def callee_id: () -> Symbol
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - defined_class()
+  # -->
   # Return class or module of the method being called.
   #
   #     class C; def foo; end; end
@@ -168,6 +212,11 @@ class TracePoint < Object
   #
   def defined_class: () -> Module
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - trace.disable               -> true or false
+  #   - trace.disable { block } -> obj
+  # -->
   # Deactivates the trace
   #
   # Return true if trace was enabled. Return false if trace was disabled.
@@ -199,6 +248,11 @@ class TracePoint < Object
   def disable: () -> bool
              | () { () -> void } -> void
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - trace.enable(target: nil, target_line: nil, target_thread: nil)    -> true or false
+  #   - trace.enable(target: nil, target_line: nil, target_thread: nil) { block }  -> obj
+  # -->
   # Activates the trace.
   #
   # Returns `true` if trace was enabled. Returns `false` if trace was disabled.
@@ -241,7 +295,7 @@ class TracePoint < Object
   #     t.enable(target: method(:m1))
   #
   #     m1
-  #     # prints #<TracePoint:line@test.rb:5 in `m1'>
+  #     # prints #<TracePoint:line test.rb:4 in `m1'>
   #     m2
   #     # prints nothing
   #
@@ -253,37 +307,71 @@ class TracePoint < Object
   def enable: () -> bool
             | () { () -> void } -> void
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - trace.enabled?          -> true or false
+  # -->
   # The current status of the trace
   #
   def enabled?: () -> bool
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - trace.inspect  -> string
+  # -->
   # Return a string containing a human-readable TracePoint status.
   #
   def inspect: () -> String
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - lineno()
+  # -->
   # Line number of the event
   #
   def lineno: () -> Integer
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - method_id()
+  # -->
   # Return the name at the definition of the method being called
   #
   def method_id: () -> Symbol
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - path()
+  # -->
   # Path of the file being run
   #
   def path: () -> String
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - raised_exception()
+  # -->
   # Value from exception raised on the `:raise` event
   #
   def raised_exception: () -> untyped
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - return_value()
+  # -->
   # Return value from `:return`, `c_return`, and `b_return` event
   #
   def return_value: () -> untyped
 
+  # <!--
+  #   rdoc-file=trace_point.rb
+  #   - self()
+  # -->
   # Return the trace object during event
   #
-  # Same as TracePoint#binding:
+  # Same as the following, except it returns the correct object (the method
+  # receiver) for `c_call` and `c_return` events:
+  #
   #     trace.binding.eval('self')
   #
   def self: () -> Binding

data/core/true_class.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=object.c -->
 # The global value `true` is the only instance of class TrueClass and represents
 # a logically true value in boolean expressions. The class provides operators
 # allowing `true` to be used in logical expressions.
@@ -7,12 +8,20 @@ class TrueClass
 
   def !: () -> false
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - true & obj    -> true or false
+  # -->
   # And---Returns `false` if *obj* is `nil` or `false`, `true` otherwise.
   #
   def &: (nil) -> false
        | (false) -> false
        | (untyped obj) -> true
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - obj === other   -> true or false
+  # -->
   # Case Equality -- For class Object, effectively the same as calling `#==`, but
   # typically overridden by descendants to provide meaningful semantics in `case`
   # statements.
@@ -20,18 +29,33 @@ class TrueClass
   def ===: (true) -> true
          | (untyped obj) -> bool
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - true ^ obj   -> !obj
+  # -->
   # Exclusive Or---Returns `true` if *obj* is `nil` or `false`, `false` otherwise.
   #
   def ^: (nil) -> true
        | (false) -> true
        | (untyped obj) -> false
 
+  # <!-- rdoc-file=object.c -->
+  # The string representation of `true` is "true".
+  #
   alias inspect to_s
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - true.to_s   ->  "true"
+  # -->
   # The string representation of `true` is "true".
   #
   def to_s: () -> "true"
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - true | obj   -> true
+  # -->
   # Or---Returns `true`. As *obj* is an argument to a method call, it is always
   # evaluated; there is no short-circuit evaluation in this case.
   #

data/core/unbound_method.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=proc.c -->
 # Ruby supports two forms of objectified methods. Class Method is used to
 # represent methods that are associated with a particular object: these method
 # objects are bound to that object. Bound method objects for an object can be
@@ -45,19 +46,28 @@
 #     um.bind(t).call   #=> :original
 #
 class UnboundMethod
+  # <!--
+  #   rdoc-file=proc.c
+  #   - method.clone -> new_method
+  # -->
   # Returns a clone of this method.
   #
-  #   class A
-  #     def foo
-  #       return "bar"
+  #     class A
+  #       def foo
+  #         return "bar"
+  #       end
   #     end
-  #   end
   #
-  #   m = A.new.method(:foo)
-  #   m.call # => "bar"
-  #   n = m.clone.call # => "bar"
+  #     m = A.new.method(:foo)
+  #     m.call # => "bar"
+  #     n = m.clone.call # => "bar"
+  #
   def clone: () -> self
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.arity    -> integer
+  # -->
   # Returns an indication of the number of arguments accepted by a method. Returns
   # a nonnegative integer for methods that take a fixed number of arguments. For
   # Ruby methods that take a variable number of arguments, returns -n-1, where n
@@ -97,6 +107,10 @@ class UnboundMethod
   #
   def arity: () -> Integer
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - umeth.bind(obj) -> method
+  # -->
   # Bind *umeth* to *obj*. If Klass was the class from which *umeth* was obtained,
   # `obj.kind_of?(Klass)` must be true.
   #
@@ -127,16 +141,28 @@ class UnboundMethod
   #
   def bind: (untyped obj) -> Method
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.name    -> symbol
+  # -->
   # Returns the name of the method.
   #
   def name: () -> Symbol
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.owner    -> class_or_module
+  # -->
   # Returns the class or module that defines the method. See also Method#receiver.
   #
   #     (1..3).method(:map).owner #=> Enumerable
   #
   def owner: () -> Module
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.parameters  -> array
+  # -->
   # Returns the parameter information of this method.
   #
   #     def foo(bar); end
@@ -154,16 +180,52 @@ class UnboundMethod
   def parameters: () -> ::Array[[ Symbol, Symbol ]]
                 | () -> ::Array[[ Symbol ]]
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.private? -> true or false
+  # -->
+  # Returns whether the method is private.
+  #
+  def private?: () -> bool
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.protected? -> true or false
+  # -->
+  # Returns whether the method is protected.
+  #
+  def protected?: () -> bool
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.public? -> true or false
+  # -->
+  # Returns whether the method is public.
+  #
+  def public?: () -> bool
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.source_location  -> [String, Integer]
+  # -->
   # Returns the Ruby source filename and line number containing this method or nil
   # if this method was not defined in Ruby (i.e. native).
   #
   def source_location: () -> [ String, Integer ]?
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.super_method  -> method
+  # -->
   # Returns a Method of superclass which would be called when super is used or nil
   # if there is no method on superclass.
   #
   def super_method: () -> UnboundMethod?
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.original_name    -> symbol
+  # -->
   # Returns the original name of the method.
   #
   #     class C
@@ -174,6 +236,10 @@ class UnboundMethod
   #
   def original_name: () -> Symbol
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - umeth.bind_call(recv, args, ...) -> obj
+  # -->
   # Bind *umeth* to *recv* and then invokes the method with the specified
   # arguments. This is semantically equivalent to `umeth.bind(recv).call(args,
   # ...)`.

data/core/warning.rbs

@@ -1,17 +1,42 @@
-# The [Warning](Warning) module contains a single
-# method named [warn](Warning#method-i-warn), and the
-# module extends itself, making `Warning.warn` available.
-# [\#warn](Warning#method-i-warn) is called for all
+# <!-- rdoc-file=error.c -->
+# The Warning module contains a single method named #warn, and the module
+# extends itself, making Warning.warn available. Warning.warn is called for all
 # warnings issued by Ruby. By default, warnings are printed to $stderr.
 #
-# By overriding [\#warn](Warning#method-i-warn), you
-# can change how warnings are handled by Ruby, either filtering some
-# warnings, and/or outputting warnings somewhere other than $stderr. When
-# [\#warn](Warning#method-i-warn) is overridden, super
-# can be called to get the default behavior of printing the warning to
-# $stderr.
+# Changing the behavior of Warning.warn is useful to customize how warnings are
+# handled by Ruby, for instance by filtering some warnings, and/or outputting
+# warnings somewhere other than $stderr.
+#
+# If you want to change the behavior of Warning.warn you should use
+# +Warning.extend(MyNewModuleWithWarnMethod)+ and you can use `super` to get the
+# default behavior of printing the warning to $stderr.
+#
+# Example:
+#     module MyWarningFilter
+#       def warn(message, category: nil, **kwargs)
+#         if /some warning I want to ignore/.match?(message)
+#           # ignore
+#         else
+#           super
+#         end
+#       end
+#     end
+#     Warning.extend MyWarningFilter
+#
+# You should never redefine Warning#warn (the instance method), as that will
+# then no longer provide a way to use the default behavior.
+#
+# The `warning` gem provides convenient ways to customize Warning.warn.
+#
 module Warning
-  # Writes warning message msg to $stderr, followed by a newline if the message does not end in a newline.
-  # This method is called by Ruby for all emitted warnings.
+  # <!--
+  #   rdoc-file=error.c
+  #   - warn(msg, category: nil)  -> nil
+  # -->
+  # Writes warning message `msg` to $stderr. This method is called by Ruby for all
+  # emitted warnings. A `category` may be included with the warning.
+  #
+  # See the documentation of the Warning module for how to customize this.
+  #
   def warn: (String) -> nil
 end

data/docs/CONTRIBUTING.md

@@ -1,46 +1,41 @@
-# Standard Library Signatures Contribution Guide
+# Core and Standard Library Signatures Contribution Guide
 
 ## Guides
 
-* [Stdlib Signatures Guide](stdlib.md)
-* [Syntax](syntax.md)
+* [RBS by Example](rbs_by_example.md)
 * [Writing Signature Guide](sigs.md)
+* [Testing Core API and Standard Library Types](stdlib.md)
+* [Syntax](syntax.md)
 
-## Steps for Contribution
+## Introduction
 
-1. Pick the class/library you will work for.
-2. Assign yourself on the [work spreadsheet](https://docs.google.com/spreadsheets/d/199rRB93I16H0k4TGZS3EGojns2R0W1oCsN8UPJzOpyU/edit#gid=1383307992) (optional but recommended to avoid duplication).
-3. Sort RBS members (if there is RBS files for the classes).
-    - Use `bin/sort stdlib/path/to/signature.rbs` command and confirm it does not break definitions.
-    - Committing the sorted RBSs is recommended.
-4. Add method prototypes.
-    - Use `rbs prototype runtime --merge CLASS_NAME` command to generate the missing method definitions.
-    - Committing the auto generated signatures is recommended.
-5. Annotate with RDoc.
-    - You'll need RDoc installed. Rvm users should use `rvm docs generate` first.
-    - Use `bin/annotate-with-rdoc stdlib/path/to/signature.rbs` to annotate the RBS files.
-    - Committing the generated annotations is recommended.
-6. Fix method types and comments.
-    - The auto generated RDoc comments include `arglists` section, which we don't expect to be included the RBS files.
-    - Delete the `arglists` sections.
-    - Give methods correct types.
-    - Write tests, if possible. (If it is too difficult to write test, skip it.)
+The RBS repository contains the type definitions of Core API and Standard Libraries.
+There are some discussions whether if it is the best to have them in this repository, but we have them and continue updating the files meanwhile.
+
+The target version of the bundled type definitions is the latest _release_ of Ruby -- `3.1` as of January 2022.
 
-## The Target Version
+**The core API** type definitions are in `core` directory.
+You will find the familiar class names in the directory, like `string.rbs` or `array.rbs`.
 
-* The standard library signatures targets Ruby 3.0 for now.
-* The library code targets Ruby 2.7 and 3.0.
+**The standard libraries** type definitions are in `stdlib` directory.
+They have the [third party repository](repo.md) structure.
+There is a `set` directory for the `set` library, and it contains `0` directory.
+Because RBS supports the latest release of Ruby, we have one set of RBS files which corresponds to the bundled versions of the libraries.
 
-## Stdlib Worksheet
+## Steps for Contribution
 
-You can find the list of classes/libraries:
+1. Pick the class/library you will work for.
+2. Make a directory `stdlib/foo/0` if you work for one of the standard libraries.
+3. Write RBS type definitions and tests.
 
-* https://docs.google.com/spreadsheets/d/199rRB93I16H0k4TGZS3EGojns2R0W1oCsN8UPJzOpyU/edit#gid=1383307992
+You will typically follow the steps as follows:
 
-Assign yourself when you start working for a class or library.
-After reviewing and merging your pull request, I will update the status of the library.
+1. Run `rbs prototype runtime` to generate list of methods.
+2. Run `rbs annotate` to import RDoc comments.
+3. Run `rbs generate:stdlib_test[LIB]` to generate a test case.
+4. Write the type definitions and tests.
 
-You may find the *Good for first contributor* column where you can find some classes are recommended for new contributors (👍), and some classes are not-recommended (👎).
+See the next *Useful Tools* section and the guides above for writing and testing RBS files.
 
 ## Useful Tools
 
@@ -49,9 +44,9 @@ You may find the *Good for first contributor* column where you can find some cla
   * `--merge` tells to use the method types in RBS if exists.
 * `rbs prototype runtime --merge --method-owner=Numeric Integer`
   * You can use --method-owner if you want to print method of other classes too, for documentation purpose.
-* `bin/annotate-with-rdoc core/string.rbs`
-  * Write comments using RDoc.
-  * It contains arglists section, but I don't think we should have it in RBS files.
+* `rbs annotate core/string.rbs`
+  * Import RDoc comments.
+  * The imported docs contain the description, *arglists*, and filenames to help writing types.
 * `bin/query-rdoc String#initialize`
   * Print RDoc documents in the format you can copy-and-paste to RBS.
 * `bin/sort core/string.rbs`
@@ -63,7 +58,7 @@ You may find the *Good for first contributor* column where you can find some cla
 * `rake test/stdlib/Array_test.rb`
   Run specific stdlib test with the path.
 
-## Standard STDLIB Members Order
+### Standard STDLIB Members Order
 
 We define the standard members order so that ordering doesn't bother reading diffs or git-annotate outputs.
 
@@ -98,3 +93,14 @@ class HelloWorld[X]
   def validate_locale: () -> void
 end
 ```
+
+## Q&A
+
+### Some of the standard libraries are gems. Why we put the files in this repo?
+
+You are correct. We want to move to their repos. We haven't started the migration yet.
+
+### How can we handle incompatibilities of core APIs and standard libraries between Rubies
+
+We ignore the incompatibilities for now.
+We focus on the latest version of core APIs and standard libraries.