rbs 2.0.0 → 2.2.2

data/sig/writer.rbs

@@ -1,4 +1,6 @@
 module RBS
+  # Writer prints RBS AST to String.
+  #
   class Writer
     interface _IO
       def puts: (*untyped) -> void
@@ -6,23 +8,96 @@ module RBS
       def flush: () -> void
     end
 
+    # Channel to output the result.
+    #
     attr_reader out: _IO
+
+    # Array of indentations.
+    #
     attr_reader indentation: Array[String]
 
     def initialize: (out: _IO) -> void
 
+    # Output the array of declarations.
+    # It automatically inserts empty lines between the declarations.
+    #
+    def write: (Array[AST::Declarations::t]) -> void
+
+    def preserve?: () -> bool
+
+    def preserve!: (?preserve: bool) -> self
+
+    private
+
+    @preserve: bool
+
+    # Increases the indentation and yields the block.
+    #
     def indent: (?Integer size) { () -> void } -> void
 
+    # Returns the current indentation of lines.
+    #
     def prefix: () -> String
 
+    # Prints a string.
+    # Automatically appends the `#prefix` and newline at the end.
+    #
     def puts: (?String) -> void
 
+    # Prints a (possibly) multi-line string.
+    #
+    # Drops `leading_spaces` of spaces at the beginning of each line.
+    #
+    # ```ruby
+    # put_lines(<<TEXT, leading_spaces: 0)
+    # Hello
+    #   world!
+    # TEXT
+    #
+    # # Outputs
+    # # Hello
+    # #   world!
+    #
+    # put_lines(<<TEXT, leading_spaces: 2)
+    # Hello
+    #   world!
+    # TEXT
+    #
+    # # Outputs
+    # # Hello
+    # # world!
+    # ```
+    #
+    # This is for `Location#source`.
+    # The `#source` returns the text spans from the beginning to end of the element.
+    # It will look like the following.
+    #
+    # ```rbs
+    # module Foo
+    #   type t = Integer     # the definition of `t` starts from line=2, column=2
+    #          | String
+    #          | :false      # the definition of `t` ends from line=4, column=17
+    # end
+    # ```
+    #
+    # The expected output will be something like:
+    #
+    # ```rbs
+    # type t = Integer       # Extracted from `Foo` definition and keeps the line breaks
+    #        | String
+    #        | :false
+    # ```
+    #
+    # And it can be done with a `#put_lines(source, leading_spaces: 2)` call.
+    #
+    def put_lines: (String, leading_spaces: Integer) -> void
+
+    def write_loc_source: (_Located) { () -> void } -> void
+
     def write_annotation: (Array[AST::Annotation]) -> void
 
     def write_comment: (AST::Comment?) -> void
 
-    def write: (Array[AST::Declarations::t]) -> void
-
     def write_decl: (AST::Declarations::t) -> void
 
     def write_member: (AST::Declarations::Module::member) -> void
@@ -31,6 +106,8 @@ module RBS
 
     def name_and_args: (TypeName, Array[Types::t]) -> String?
 
+    def write_alias: (AST::Declarations::Alias) -> void
+
     def method_name: (Symbol) -> String
 
     def write_def: (AST::Members::MethodDefinition) -> void

data/stdlib/abbrev/0/abbrev.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=lib/abbrev.rb -->
 # Calculates the set of unambiguous abbreviations for a given set of strings.
 #
 #     require 'abbrev'
@@ -34,6 +35,10 @@
 #       "w"       => "winter" }
 #
 module Abbrev
+  # <!--
+  #   rdoc-file=lib/abbrev.rb
+  #   - abbrev(words, pattern = nil)
+  # -->
   # Given a set of strings, calculate the set of unambiguous abbreviations for
   # those strings, and return a hash where the keys are all the possible
   # abbreviations and the values are the full strings.
@@ -56,5 +61,6 @@ module Abbrev
   #
   #     Abbrev.abbrev(%w{car box cone}, 'ca')
   #     #=> {"car"=>"car", "ca"=>"car"}
+  #
   def self?.abbrev: (Array[String], ?String | Regexp | nil) -> Hash[String, String]
 end

data/stdlib/abbrev/0/array.rbs

@@ -0,0 +1,26 @@
+%a{annotate:rdoc:skip}
+class Array[unchecked out Elem]
+  # <!--
+  #   rdoc-file=lib/abbrev.rb
+  #   - abbrev(pattern = nil)
+  # -->
+  # Calculates the set of unambiguous abbreviations for the strings in `self`.
+  #
+  #     require 'abbrev'
+  #     %w{ car cone }.abbrev
+  #     #=> {"car"=>"car", "ca"=>"car", "cone"=>"cone", "con"=>"cone", "co"=>"cone"}
+  #
+  # The optional `pattern` parameter is a pattern or a string. Only input strings
+  # that match the pattern or start with the string are included in the output
+  # hash.
+  #
+  #     %w{ fast boat day }.abbrev(/^.a/)
+  #     #=> {"fast"=>"fast", "fas"=>"fast", "fa"=>"fast", "day"=>"day", "da"=>"day"}
+  #
+  #     Abbrev.abbrev(%w{car box cone}, "ca")
+  #     #=> {"car"=>"car", "ca"=>"car"}
+  #
+  # See also Abbrev.abbrev
+  #
+  def abbrev: (?String | Regexp | nil) -> Hash[String, String]
+end

data/stdlib/base64/0/base64.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=lib/base64.rb -->
 # The Base64 module provides for the encoding (#encode64, #strict_encode64,
 # #urlsafe_encode64) and decoding (#decode64, #strict_decode64,
 # #urlsafe_decode64) of binary data using a Base64 representation.
@@ -17,6 +18,10 @@
 # data into purely printable characters.
 #
 module Base64
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - decode64(str)
+  # -->
   # Returns the Base64-decoded version of `str`. This method complies with RFC
   # 2045. Characters outside the base alphabet are ignored.
   #
@@ -32,8 +37,13 @@ module Base64
   #     This is line two
   #     This is line three
   #     And so on...
+  #
   def self?.decode64: (String str) -> String
 
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - encode64(bin)
+  # -->
   # Returns the Base64-encoded version of `bin`. This method complies with RFC
   # 2045. Line feeds are added to every 60 encoded characters.
   #
@@ -44,28 +54,49 @@ module Base64
   #
   #     Tm93IGlzIHRoZSB0aW1lIGZvciBhbGwgZ29vZCBjb2RlcnMKdG8gbGVhcm4g
   #     UnVieQ==
+  #
   def self?.encode64: (String bin) -> String
 
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - strict_decode64(str)
+  # -->
   # Returns the Base64-decoded version of `str`. This method complies with RFC
   # 4648. ArgumentError is raised if `str` is incorrectly padded or contains
   # non-alphabet characters.  Note that CR or LF are also rejected.
+  #
   def self?.strict_decode64: (String str) -> String
 
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - strict_encode64(bin)
+  # -->
   # Returns the Base64-encoded version of `bin`. This method complies with RFC
   # 4648. No line feeds are added.
+  #
   def self?.strict_encode64: (String bin) -> String
 
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - urlsafe_decode64(str)
+  # -->
   # Returns the Base64-decoded version of `str`. This method complies with ``Base
   # 64 Encoding with URL and Filename Safe Alphabet'' in RFC 4648. The alphabet
   # uses '-' instead of '+' and '_' instead of '/'.
   #
   # The padding character is optional. This method accepts both correctly-padded
   # and unpadded input. Note that it still rejects incorrectly-padded input.
+  #
   def self?.urlsafe_decode64: (String str) -> String
 
+  # <!--
+  #   rdoc-file=lib/base64.rb
+  #   - urlsafe_encode64(bin, padding: true)
+  # -->
   # Returns the Base64-encoded version of `bin`. This method complies with ``Base
   # 64 Encoding with URL and Filename Safe Alphabet'' in RFC 4648. The alphabet
   # uses '-' instead of '+' and '_' instead of '/'. Note that the result can still
   # contain '='. You can remove the padding by setting `padding` as false.
+  #
   def self?.urlsafe_encode64: (String bin, ?padding: boolish) -> String
 end

data/stdlib/benchmark/0/benchmark.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=lib/benchmark.rb -->
 # The Benchmark module provides methods to measure and report the time used to
 # execute Ruby code.
 #
@@ -101,13 +102,19 @@
 #         >total:   2.880000   0.000000   2.880000 (  2.883764)
 #         >avg:     0.960000   0.000000   0.960000 (  0.961255)
 #
-#
 module Benchmark
+  # <!--
+  #   rdoc-file=lib/benchmark.rb
+  #   - benchmark(caption = "", label_width = nil, format = nil, *labels) { |report| ... }
+  # -->
   # Invokes the block with a Benchmark::Report object, which may be used to
   # collect and report on the results of individual benchmark tests. Reserves
   # `label_width` leading spaces for labels on each line. Prints `caption` at the
-  # top of the report, and uses `format` to format each line. Returns an array of
-  # Benchmark::Tms objects.
+  # top of the report, and uses `format` to format each line. (Note: `caption`
+  # must contain a terminating newline character, see the default
+  # Benchmark::Tms::CAPTION for an example.)
+  #
+  # Returns an array of Benchmark::Tms objects.
   #
   # If the block returns an array of Benchmark::Tms objects, these will be used to
   # format additional lines of output. If `labels` parameter are given, these are
@@ -141,6 +148,10 @@ module Benchmark
   #
   def self?.benchmark: (String caption, ?Integer? label_width, ?String? format, *String labels) { (Report report) -> (Array[Tms] | void) } -> Array[Tms]
 
+  # <!--
+  #   rdoc-file=lib/benchmark.rb
+  #   - bm(label_width = 0, *labels) { |report| ... }
+  # -->
   # A simple interface to the #benchmark method, #bm generates sequential reports
   # with labels. `label_width` and `labels` parameters have the same meaning as
   # for #benchmark.
@@ -163,6 +174,10 @@ module Benchmark
   #
   def self?.bm: (?Integer label_width, *String labels) { (Report report) -> void } -> Array[Tms]
 
+  # <!--
+  #   rdoc-file=lib/benchmark.rb
+  #   - bmbm(width = 0) { |job| ... }
+  # -->
   # Sometimes benchmark results are skewed because code executed earlier
   # encounters different garbage collection overheads than that run later. #bmbm
   # attempts to minimize this effect by running the tests twice, the first time as
@@ -200,6 +215,10 @@ module Benchmark
   #
   def self?.bmbm: (?Integer width) { (Job job) -> void } -> Array[Tms]
 
+  # <!--
+  #   rdoc-file=lib/benchmark.rb
+  #   - measure(label = "") { || ... }
+  # -->
   # Returns the time used to execute the given block as a Benchmark::Tms object.
   # Takes `label` option.
   #
@@ -218,16 +237,22 @@ module Benchmark
   #
   def self?.measure: (?String label) { () -> void } -> Tms
 
+  # <!--
+  #   rdoc-file=lib/benchmark.rb
+  #   - realtime() { || ... }
+  # -->
   # Returns the elapsed real time used to execute the given block.
   #
   def self?.realtime: () { () -> void } -> Float
 
   BENCHMARK_VERSION: String
 
+  # <!-- rdoc-file=lib/benchmark.rb -->
   # The default caption string (heading above the output times).
   #
   CAPTION: String
 
+  # <!-- rdoc-file=lib/benchmark.rb -->
   # The default format string used to display times.  See also
   # Benchmark::Tms#format.
   #
@@ -260,50 +285,81 @@ module Benchmark
     alias report item
   end
 
+  # <!-- rdoc-file=lib/benchmark.rb -->
   # A data object, representing the times associated with a benchmark measurement.
   #
   class Tms
+    # <!--
+    #   rdoc-file=lib/benchmark.rb
+    #   - *(x)
+    # -->
     # Returns a new Tms object obtained by memberwise multiplication of the
     # individual times for this Tms object by `x`.
     #
     def *: (untyped x) -> untyped
 
+    # <!--
+    #   rdoc-file=lib/benchmark.rb
+    #   - +(other)
+    # -->
     # Returns a new Tms object obtained by memberwise summation of the individual
     # times for this Tms object with those of the `other` Tms object. This method
     # and #/() are useful for taking statistics.
     #
     def +: (untyped other) -> untyped
 
+    # <!--
+    #   rdoc-file=lib/benchmark.rb
+    #   - -(other)
+    # -->
     # Returns a new Tms object obtained by memberwise subtraction of the individual
     # times for the `other` Tms object from those of this Tms object.
     #
     def -: (untyped other) -> untyped
 
+    # <!--
+    #   rdoc-file=lib/benchmark.rb
+    #   - /(x)
+    # -->
     # Returns a new Tms object obtained by memberwise division of the individual
     # times for this Tms object by `x`. This method and #+() are useful for taking
     # statistics.
     #
     def /: (untyped x) -> untyped
 
+    # <!--
+    #   rdoc-file=lib/benchmark.rb
+    #   - add() { || ... }
+    # -->
     # Returns a new Tms object whose times are the sum of the times for this Tms
     # object, plus the time required to execute the code block (`blk`).
     #
     def add: () { (*untyped) -> untyped } -> untyped
 
+    # <!--
+    #   rdoc-file=lib/benchmark.rb
+    #   - add!(&blk)
+    # -->
     # An in-place version of #add. Changes the times of this Tms object by making it
     # the sum of the times for this Tms object, plus the time required to execute
     # the code block (`blk`).
     #
     def add!: () { (*untyped) -> untyped } -> untyped
 
+    # <!-- rdoc-file=lib/benchmark.rb -->
     # System CPU time of children
     #
     def cstime: () -> Float
 
+    # <!-- rdoc-file=lib/benchmark.rb -->
     # User CPU time of children
     #
     def cutime: () -> Float
 
+    # <!--
+    #   rdoc-file=lib/benchmark.rb
+    #   - format(format = nil, *args)
+    # -->
     # Returns the contents of this Tms object as a formatted string, according to a
     # `format` string like that passed to Kernel.format. In addition, #format
     # accepts the following extensions:
@@ -331,40 +387,55 @@ module Benchmark
     #
     def format: (?String format, *untyped args) -> String
 
+    # <!-- rdoc-file=lib/benchmark.rb -->
     # Label
     #
     def label: () -> String
 
+    # <!-- rdoc-file=lib/benchmark.rb -->
     # Elapsed real time
     #
     def real: () -> Float
 
+    # <!-- rdoc-file=lib/benchmark.rb -->
     # System CPU time
     #
     def stime: () -> Float
 
+    # <!--
+    #   rdoc-file=lib/benchmark.rb
+    #   - to_a()
+    # -->
     # Returns a new 6-element array, consisting of the label, user CPU time, system
     # CPU time, children's user CPU time, children's system CPU time and elapsed
     # real time.
     #
     def to_a: () -> untyped
 
+    # <!--
+    #   rdoc-file=lib/benchmark.rb
+    #   - to_s()
+    # -->
     # Same as #format.
     #
     def to_s: () -> String
 
+    # <!-- rdoc-file=lib/benchmark.rb -->
     # Total time, that is `utime` + `stime` + `cutime` + `cstime`
     #
     def total: () -> Float
 
+    # <!-- rdoc-file=lib/benchmark.rb -->
     # User CPU time
     #
     def utime: () -> Float
 
+    # <!-- rdoc-file=lib/benchmark.rb -->
     # Default caption, see also Benchmark::CAPTION
     #
     CAPTION: String
 
+    # <!-- rdoc-file=lib/benchmark.rb -->
     # Default format string, see also Benchmark::FORMAT
     #
     FORMAT: String