rbs 4.1.0.pre.2-java

data/docs/architecture.md

@@ -0,0 +1,110 @@
+# Architecture
+
+This guide describes the outline of the architecture of RBS library. It helps you to understand the structure and key features of the library to start contributing to the library.
+
+## Bird's Eye View
+
+The goal of the library is simple: Read RBS files and generate the structure of Ruby programs.
+
+```
+RBS files
+  ↓         -- RBS::Parser
+Syntax tree
+  ↓
+Environment
+  ↓        -- Definition builder
+Definition
+```
+
+The input is RBS files. The gem ships with RBS type definitions of Ruby core library and some of the standard libraries. You write RBS files for your applications or gems.
+
+Syntax tree is the next representation. `RBS::Parser` transforms the sequence of characters in RBS files into syntax trees.
+
+Syntax tree objects are loaded to `RBS::Environment`. It collects loaded RBS objects, organizes the definitions, and provides some utilities, like resolving type names and finding the declarations.
+
+`RBS::Definition` is the goal of the transformation steps. It is associated with a class singleton, a class object, or an interface. You can find the list of available methods and their types, instance variables, and class hierarchies.
+
+## Core classes
+
+### Types
+
+Types are defined under `RBS::Types`, like `RBS::Types::ClassInstance` or `RBS::Types::Union`. You will find the definition of each type supported in RBS.
+
+### Parsing RBS files
+
+The RBS source code is loaded into `RBS::Buffer`, and `RBS::Parser` is the parser. The parser is implemented in C extension.
+
+`RBS::Parser` provides three entrypoints.
+
+- `RBS::Parser.parse_method_type` parsers a *method type*. (`[T] (String) { (IO) -> T } -> Array[T]`)
+- `RBS::Parser.parse_type` parses a *type*. (`Hash[Symbol, untyped]`)
+- `RBS::Parser.parse_signature` parses the whole RBS file.
+
+### Environment
+
+RBS AST is loaded to `RBS::Environment` by `RBS::EnvironmentLoader`. `Environment` gives *absolute names* to the declarations, and provides an index from the *absolute name* to their declarations.
+
+Assume we have the following nested RBS declarations:
+
+```rbs
+module Hello
+  class World
+  end
+end
+
+class Hello::World
+end
+```
+
+And the environment organizes the definitions as follows:
+
+- There are two classes `::Hello` and `::Hello::World`
+- It provides a mapping from `::Hello` to it's `module` declaration and `::Hello::World` to it's two `class` declarations
+
+### Definition and DefinitionBuilder
+
+`RBS::Definition` tells you:
+
+- The set of available methods in a class/module/interface
+- The set of instance variables in a class/module
+- The ancestors in a class/module
+
+Definition is constructed for:
+
+- A singleton class of a class/module -- `singleton(String)`, `singleton(Array)`,
+- An instance of a class -- `String`, `Array[T]`, or
+- An interface -- `_ToS`
+
+Note that generic class instances/interfaces are kept generic. We don't have a definition of `Array[String]` but of `Array[T]`.
+
+`DefinitionBuilder` constructs `Definition` of given type names.
+
+- `DefinitionBuilder#build_singleton` returns a definition of singleton classes of given class/module.
+- `DefinitionBuilder#build_instance` returns a definition of instances of given class/module.
+- `DefinitionBuilder#build_interface` returns a definition of interfaces.
+
+It uses `AncestorBuilder` to construct ancestor chains of the type. `MethodBuilder` constructs sets of available methods based on the ancestor chains.
+
+The `#build_singleton` calculates the type of `.new` methods based on the definition of `#initialize` method. This is different from Ruby's implementation -- it reused `Class#new` method but we need the custom implementation to give precise `.new` method type of each class.
+
+#### Working with type aliases
+
+`DefinitionBuilder#expand_alias` and its variants provide one step *unfold* operation of type aliases.
+
+```ruby
+builder.expand_alias2(RBS::TypeName.parse("::int"), []) # => returns `::Integer | ::_ToInt`
+```
+
+We don't have *normalize* operation for type aliases, because RBS allows recursive type alias definition, which cannot be *fully* unfolded.
+
+### Other utilities
+
+`RBS::Validator` provides validation of RBS type declaration. It validates that all of the type name references can be resolved, all type applications have correct arity, and so on.
+
+`RBS::Test` provides runtime type checking, which confirms if a Ruby object can have an RBS type. It also provides an integration to existing Ruby code so that we run Ruby code, assuming unit tests, with runtime type checking.
+
+`RBS::UnitTest` provides utilities to help write unit tests for RBS type definitions. Use the tool to make sure your RBS type definition is consistent with implementation.
+
+`RBS::Prototype` is the core of `rbs prototype` feature. It scans Ruby source code or uses reflection features, and it generates the prototype of RBS files.
+
+`RBS::Collection` includes `rbs collection` features.

data/docs/collection.md

@@ -0,0 +1,192 @@
+# RBS Collection manager
+
+`rbs collection` sub command manages third party gems' RBS. In short, it is `bundler` for RBS.
+
+## Requirements
+
+* `git(1)`
+* `Gemfile.lock`
+
+## Usage
+
+### Setup
+
+First, generate the configuration file, `rbs_collection.yaml`, with `rbs collection init`.
+
+```console
+$ rbs collection init
+created: rbs_collection.yaml
+
+$ cat rbs_collection.yaml
+# Download sources
+sources:
+  - name: ruby/gem_rbs_collection
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    revision: main
+    repo_dir: gems
+
+# A directory to install the downloaded RBSs
+path: .gem_rbs_collection
+
+# gems:
+#   # If you want to avoid installing rbs files for gems, you can specify them here.
+#   - name: GEM_NAME
+#     ignore: true
+```
+
+I also recommend updating `.gitignore`.
+
+```console
+$ echo /.gem_rbs_collection/ >> .gitignore
+```
+
+### Install dependencies
+
+Then, install gems' RBS with `rbs collection install`! It copies RBS from [the gem RBS repository](https://github.com/ruby/gem_rbs_collection) to `.gem_rbs_collection/` directory by default.
+I recommend to ignore `.gem_rbs_collection/` from version control system, such as Git.
+
+```console
+$ rbs collection install
+Installing ast:2.4 (ruby/gem_rbs_collection@4b1a2a2f64c)
+...
+It's done! 42 gems's RBSs now installed.
+```
+
+Finally the third party RBSs are available! `rbs` commands, such as `rbs validate`, automatically load the third party RBSs.
+
+### Other commands
+
+`rbs collection` has two more commands.
+
+* `rbs collection update` updates `rbs_collection.lock.yaml`.
+* `rbs collection clean` removes unnecessary rbs from `.gem_rbs_collection` directory.
+
+## Configuration
+
+### `rbs_collection.yaml`
+
+Configure `rbs collection` with editing `rbs_collection.yaml`.
+
+```yaml
+# rbs_collection.yaml
+
+# Download sources.
+# You can add own collection git repository.
+sources:
+  - name: ruby/gem_rbs_collection
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    revision: main
+    repo_dir: gems
+
+  # You can also add a local path as a collection source optionally.
+  - type: local
+    path: path/to/local/dir
+
+# A directory to install the downloaded RBSs
+path: .gem_rbs_collection
+
+gems:
+  # If the Gemfile.lock doesn't contain csv gem but you use csv gem,
+  # you can write the gem name explicitly to install RBS of the gem.
+  - name: csv
+
+  # If the Gemfile.lock contains nokogiri gem but you don't want to use the RBS,
+  # you can ignore the gem.
+  # `rbs collection` avoids to install nokogiri gem's RBS by this change.
+  # It is useful if the nokogiri RBS has a problem, such as compatibility issue with other RBS.
+  - name: nokogiri
+    ignore: true
+```
+
+### Avoid installing RBS
+
+There are two ways to avoid RBS installation.
+
+#### `require: false` in `Gemfile`
+
+First, you can specify `require: false` in `Gemfile`. It is the recommended way to avoid installing RBS.
+For example:
+
+```ruby
+# Gemfile
+
+gem 'GEM_NAME', require: false
+```
+
+In this case, `rbs collection` doesn't install the RBS of `GEM_NAME`.
+We recommend to specify `require: false` for `rbs` gem itself because `rbs` gem's RBS file is not necessary in most cases.
+
+#### `ignore: true` in `rbs_collection.yaml`
+
+Second, you can write `ignore: true` in `rbs_collection.yaml`. It is useful if you want to avoid installing RBS but you need to require the gem.
+
+```yaml
+# rbs_collection.yaml
+
+gems:
+  - name: GEM_NAME
+    ignore: true
+```
+
+#### Load RBS specified `require: false`
+
+You can also use `ignore: false` if you want to install RBS for a gem which you specify `require: false` in `Gemfile`.
+For example:
+
+```ruby
+# Gemfile
+
+gem 'GEM_NAME', require: false
+```
+
+```yaml
+# rbs_collection.yaml
+
+gems:
+  - name: GEM_NAME
+    ignore: false
+```
+
+In this case, `rbs collection` installs the RBS of `GEM_NAME`.
+
+### `manifest.yaml`
+
+If you are a gem maintainer, you can write `manifest.yaml`.
+You need to put the file if the gem has implicit dependencies, which don't appear in `Gemfile.lock`. You have to write standard libraries' dependencies in most cases.
+For example:
+
+```yaml
+# manifest.yaml
+
+dependencies:
+  # If your gem depends on logger but the gemspec doesn't include logger,
+  # you need to write the following.
+  - name: logger
+```
+
+If the gem's RBS is managed with [ruby/gem_rbs_collection](https://github.com/ruby/gem_rbs_collection), put it as `gems/GEM_NAME/VERSION/manifest.yaml`.  For example, `gems/activesupport/6.0/manifest.yaml`.
+If the gem's RBS is included in the gem package, put it as `sig/manifest.yaml`.
+
+
+## Files / Directories
+
+* `rbs_collection.yaml`
+  * The configuration file.
+  * You need to edit it if:
+    * You don't want to ignore gem's RBS.
+    * You want to add gem's RBS explicitly.
+  * You can change the file path with `--collection` option. e.g. `rbs --collection another_conf.yaml collection install`.
+* `rbs_collection.lock.yaml`
+  * RBS installs and loads RBS files with this file.
+  * It is auto-generated file. Do not edit this file.
+  * I recommend to manage it with VCS such as git.
+* `.gem_rbs_collection/`
+  * RBS installs third party RBS files to the directory.
+  * I recommend to ignore it from VCS.
+  * You can change the path with `path` option of `rbs_collection.yaml` file.
+
+
+## How it works
+
+`rbs collection` is integrated with Bundler.
+`rbs collection install` command generates `rbs_collection.lock.yaml` from `rbs_collection.yaml` and `Gemfile.lock`. It uses `Gemfile.lock` to detects dependencies.

data/docs/config.md

@@ -0,0 +1,171 @@
+# config.yml
+
+`config.yml` is the definition of data structure for parser results -- AST.
+
+It defines the data structure for the parser implementation in C and Rust `node` modules.
+
+## C parser code
+
+```sh
+$ rake templates
+```
+
+Our C parser consists of two components:
+
+1. Pure C Parser
+2. Translator from the pure C AST to Ruby object
+
+`config.yml` defines the AST for pure C parser in `ast.h`/`ast.c` and translator from the C AST to Ruby objects in `ast_translation.h`/`ast_translation.c`.
+
+## `ruby-rbs` crate
+
+```sh
+$ cd rust; cargo build
+```
+
+The `build.rs` in `ruby-rbs` crate defines the data structure derived from `config.yml` definitions under `node` module.
+
+## nodes
+
+`nodes` defines *node* data types in C or Rust.
+
+```yaml
+nodes:
+  - name: RBS::AST::Declarations::Class
+    rust_name: ClassNode
+    fields:
+      - name: name
+        c_type: rbs_type_name
+      - name: type_params
+        c_type: rbs_node_list
+      - name: super_class
+        c_type: rbs_ast_declarations_class_super
+        optional: true  # NULL when no superclass (e.g., `class Foo end` vs `class Foo < Bar end`)
+      - name: members
+        c_type: rbs_node_list
+      - name: annotations
+        c_type: rbs_node_list
+      - name: comment
+        c_type: rbs_ast_comment
+        optional: true  # NULL when no comment precedes the declaration
+```
+
+This defines `rbs_ast_declarations_class` struct so that the parser constructs the AST using the structs.
+
+```c
+typedef struct rbs_ast_declarations_class {
+    rbs_node_t base;
+
+    struct rbs_type_name *name;
+    struct rbs_node_list *type_params;
+    struct rbs_ast_declarations_class_super *super_class; /* Optional */
+    struct rbs_node_list *members;
+    struct rbs_node_list *annotations;
+    struct rbs_ast_comment *comment; /* Optional */
+
+    rbs_location_range keyword_range;     /* Required */
+    rbs_location_range name_range;        /* Required */
+    rbs_location_range end_range;         /* Required */
+    rbs_location_range type_params_range; /* Optional */
+    rbs_location_range lt_range;          /* Optional */
+} rbs_ast_declarations_class_t;
+```
+
+The `rbs_ast_declarations_class` struct is a pure C AST, and `ast_translation.c` defines translation into a Ruby object of `RBS::AST::Declarations::Class` class.
+
+```c
+    case RBS_AST_DECLARATIONS_CLASS: {
+        rbs_ast_declarations_class_t *node = (rbs_ast_declarations_class_t *) instance;
+
+        VALUE h = rb_hash_new();
+        VALUE location = rbs_location_range_to_ruby_location(ctx, node->base.location);
+        rbs_loc *loc = rbs_check_location(location);
+        rbs_loc_legacy_alloc_children(loc, 5);
+        rbs_loc_legacy_add_required_child(loc, rb_intern("keyword"), (rbs_loc_range) { .start = node->keyword_range.start_char, .end = node->keyword_range.end_char });
+        rbs_loc_legacy_add_required_child(loc, rb_intern("name"), (rbs_loc_range) { .start = node->name_range.start_char, .end = node->name_range.end_char });
+        rbs_loc_legacy_add_required_child(loc, rb_intern("end"), (rbs_loc_range) { .start = node->end_range.start_char, .end = node->end_range.end_char });
+        rbs_loc_legacy_add_optional_child(loc, rb_intern("type_params"), (rbs_loc_range) { .start = node->type_params_range.start_char, .end = node->type_params_range.end_char });
+        rbs_loc_legacy_add_optional_child(loc, rb_intern("lt"), (rbs_loc_range) { .start = node->lt_range.start_char, .end = node->lt_range.end_char });
+        rb_hash_aset(h, ID2SYM(rb_intern("location")), location);
+        rb_hash_aset(h, ID2SYM(rb_intern("name")), rbs_struct_to_ruby_value(ctx, (rbs_node_t *) node->name)); // rbs_type_name
+        rb_hash_aset(h, ID2SYM(rb_intern("type_params")), rbs_node_list_to_ruby_array(ctx, node->type_params));
+        rb_hash_aset(h, ID2SYM(rb_intern("super_class")), rbs_struct_to_ruby_value(ctx, (rbs_node_t *) node->super_class)); // rbs_ast_declarations_class_super
+        rb_hash_aset(h, ID2SYM(rb_intern("members")), rbs_node_list_to_ruby_array(ctx, node->members));
+        rb_hash_aset(h, ID2SYM(rb_intern("annotations")), rbs_node_list_to_ruby_array(ctx, node->annotations));
+        rb_hash_aset(h, ID2SYM(rb_intern("comment")), rbs_struct_to_ruby_value(ctx, (rbs_node_t *) node->comment)); // rbs_ast_comment
+
+        rb_funcall(
+            RBS_AST_TypeParam,
+            rb_intern("resolve_variables"),
+            1,
+            rb_hash_lookup(h, ID2SYM(rb_intern("type_params")))
+        );
+        return CLASS_NEW_INSTANCE(
+            RBS_AST_Declarations_Class,
+            1,
+            &h
+        );
+    }
+```
+
+## enums
+
+`enums` defines *enum* data types in C or Rust.
+
+```yaml
+enums:
+  attribute_visibility:
+    optional: true
+    symbols:
+      - unspecified
+      - public
+      - private
+```
+
+For example, the `attribute_visibility` enum is a data type for `visibility` attribute of `attr_reader`, `attr_writer`, and `attr_accessor` definitions.
+The `visibility` attribute can be one of `unspecified`, `public`, and `private`.
+
+### Symbol enums
+
+Enum definition with `symbols:` attribute defines *enum* data that is mapped to Ruby symbols.
+
+```yaml
+enums:
+  attribute_visibility:
+    optional: true
+    symbols:
+      - unspecified
+      - public
+      - private
+```
+
+It defines an `enum` in C AST definition.
+
+```c
+enum RBS_ATTRIBUTE_VISIBILITY_TAG {
+    RBS_ATTRIBUTE_VISIBILITY_TAG_UNSPECIFIED,
+    RBS_ATTRIBUTE_VISIBILITY_TAG_PUBLIC,
+    RBS_ATTRIBUTE_VISIBILITY_TAG_PRIVATE,
+};
+```
+
+The C extension also defines a translation:
+
+```c
+VALUE rbs_attribute_visibility_to_ruby(enum rbs_attribute_visibility value) {
+    switch (value) {
+    case RBS_ATTRIBUTE_VISIBILITY_UNSPECIFIED:
+        return Qnil;
+    case RBS_ATTRIBUTE_VISIBILITY_PUBLIC:
+        return rb_id2sym(rb_intern("public"));
+    case RBS_ATTRIBUTE_VISIBILITY_PRIVATE:
+        return rb_id2sym(rb_intern("private"));
+    default:
+        rb_fatal("unknown enum rbs_attribute_visibility value: %d", value);
+    }
+}
+```
+
+`RBS_ATTRIBUTE_VISIBILITY_PUBLIC` and `RBS_ATTRIBUTE_VISIBILITY_PRIVATE` are translated to Ruby symbols `:public` and `:private` respectively. 
+
+Note that the first `RBS_ATTRIBUTE_VISIBILITY_UNSPECIFIED` is translated to `nil` in Ruby. This is specified by the `optional: true` attribute in YAML. When `optional: true` is set, the first enum value is translated to `nil`.

data/docs/data_and_struct.md

@@ -0,0 +1,86 @@
+# Using `Data` and `Struct`
+
+`Data` and `Struct` are commonly used utilities to define simple *value* objects. The objects have attributes, and the equality between the two objects are defined by equality of the attributes. (Note that we can define additional methods and overwrite the equality definitions when we want.)
+
+```ruby
+# Defines `Measure` class with `#amount` and `#unit` attributes
+Measure = Data.define(:amount, :unit)
+```
+
+Unfortunately, supporting `Data` and `Struct` in RBS is not straightforward. You have to write down the attribute definitions and initializers in RBS.
+
+```rbs
+class Measure
+  # `attr_accessor amount: Integer` in the case of Struct
+  attr_reader amount: Integer
+  
+  # `attr_accessor unit: String` in the case of Struct
+  attr_reader unit: String
+  
+  def initialize: (Integer amount, String unit) -> void
+                | (amount: Integer, unit: String) -> void             
+end
+```
+
+This is simplified definition of the `Measure` class, for the case you only use the attributes and initializers. You can add more method definitions or inherit from `Data` class to make the definition more complete.
+
+However, it's common that you don't need all of the `Data` and `Struct` methods, like `.members` and `.[]`. When you are using those utility classes just for the attributes methods, you can simply ignore other methods or skip specifying a super class.
+
+> You may want to implement a generator that understands `Data.define` and `Struct.new`. But even with the generator, you need to edit the generated RBS files so that the attribute definitions have correct types.
+
+## Type checking class definitions using `Data` and `Struct`
+
+If you use Steep, you may need additional annotation in Ruby implementation.
+
+```ruby
+# Type error because return type of `Data.define(...)` is not `singleton(Measure)`
+Measure = Data.define(:amount, :unit)
+```
+
+You can please the type checker by adding a cast (`_`) or define the class inheriting from `Data.define(...)`.
+
+```ruby
+# Skip type checking by assigning to `_`
+Measure = _ = Data.define(:amount, :unit)
+
+# Super class is not type checked by Steep
+class Measure < Data.define(:amount, :unit)
+end
+```
+
+@soutaro has prefered inheriting from `Data.define`, but you may find an extra annonymous class in `.ancestors` [^1].
+
+```ruby
+Measure.ancestors #=> [Measure, #<Class:0xOOF>, Data, ...]
+```
+
+[^1]: [Shannon Skipper](https://github.com/havenwood) told me it in Discord
+
+## Generate prototype for `Data` and `Struct`
+
+RBS prototypes for classes using `Data` and `Struct` can be generated by `rbs prototype runtime`.
+
+```rb
+# t.rb
+class Measure < Data.define(:amount, :unit)
+end
+```
+
+```
+$ bundle exec rbs prototype runtime -R t.rb Measure
+class Measure < ::Data
+  def self.new: (untyped amount, untyped unit) -> instance
+              | (amount: untyped, unit: untyped) -> instance
+
+  def self.[]: (untyped amount, untyped unit) -> instance
+             | (amount: untyped, unit: untyped) -> instance
+
+  def self.members: () -> [ :amount, :unit ]
+
+  def members: () -> [ :amount, :unit ]
+
+  attr_reader amount: untyped
+
+  attr_reader unit: untyped
+end
+```

data/docs/encoding.md

@@ -0,0 +1,56 @@
+# RBS File Encoding
+
+## Best Practice
+
+**Use UTF-8** for both file encoding and your system locale.
+
+## Supported Encodings
+
+RBS parser supports ASCII-compatible encodings (similar to Ruby's script encoding support).
+
+**Examples**: UTF-8, US-ASCII, Shift JIS, EUC-JP, ...
+
+## Unicode Codepoint Symbols
+
+String literal types in RBS can contain Unicode codepoint escape sequences (`\uXXXX`).
+
+When the file encoding is UTF-8, the parser translates Unicode codepoint symbols:
+
+```rbs
+# In UTF-8 encoded files
+
+type t = "\u0123"  # Translated to the actual Unicode character ģ
+type s = "\u3042"  # Translated to the actual Unicode character あ
+```
+
+When the file encoding is not UTF-8, Unicode escape sequences are interpreted literally as the string `\uXXXX`:
+
+```rbs
+# In non-UTF-8 encoded files
+
+type t = "\u0123"  # Remains as the literal string "\u0123"
+```
+
+## Implementation
+
+RBS gem currently doesn't do anything for file encoding. It relies on Ruby's encoding handling, specifically `Encoding.default_external` and `Encoding.default_internal`.
+
+`Encoding.default_external` is the encoding Ruby assumes when it reads external resources like files. The Ruby interpreter sets it based on the locale. `Encoding.default_internal` is the encoding Ruby converts the external resources to. The default is `nil` (no conversion.)
+
+When your locale is set to use `UTF-8` encoding, `default_external` is `Encoding::UTF_8`. So the RBS file content read from the disk will have UTF-8 encoding.
+
+### Parsing non UTF-8 RBS source text
+
+If you want to work with another encoding, ensure the source string has ASCII compatible encoding.
+
+```ruby
+source = '"日本語"'
+RBS::Parser.parse_type(source.encode(Encoding::EUC_JP))  # => Parses successfully
+RBS::Parser.parse_type(source.encode(Encoding::UTF_32))  # => Returns `nil` since UTF-32 is not ASCII compatible
+```
+
+### Specifying file encoding
+
+Currently, RBS doesn't support specifying file encoding directly.
+
+You can use `Encoding.default_external` while the gem loads RBS files from the storage.

data/docs/gem.md

@@ -0,0 +1,56 @@
+# Releasing a gem with RBS
+
+You can release the RBS type definition of your gem included in the gem package. Just add your RBS files inside `/sig` directory, put them in your rubygem package, and release a new version. RBS gem will load the RBS files from your gem package automatically.
+
+## `/sig` directory
+
+RBS gem tries to load a type definition of a gem from gem package first. It checks if there is `/sig` directory in the gem package and loads `*.rbs` files from the directory. So, everything you have to do to make your type definition available are:
+
+1. Add `/sig` directory in your gem package
+2. Put your RBS files inside the directory
+3. Make sure the RBS files are included in the gem package
+
+### Hidden RBS files
+
+If you have RBS files you don't want to export to the gem users, you can put the files under a directory that starts with `_``.
+
+Assume you have three RBS files in your gem package:
+
+* `/sig/foo.rbs`
+* `/sig/bar/baz.rbs`
+* `/sig/_private/internal.rbs`
+
+`foo.rbs` and `baz.rbs` will be loaded from the gem package, but the `internal.rbs` will be skipped. This is only when you load RBS files of a *library*, for example through `-r` option given to `rbs` command. If you load RBS files as *source code*, for example through `-I` option given to `rbs` command, the hidden RBS files will be loaded too.
+
+* `rbs -r your-gem` => Loading a library
+* `rbs -I sig` => Loading RBS files as source code
+
+### Adding `manifest.yaml`
+
+`manifest.yaml` lets you declare dependencies to standard libraries. Here is an example, from [RBS gem](https://github.com/ruby/rbs/blob/6b3d0f976a50b3974d0bff26ea8fa9931053f38b/sig/manifest.yaml).
+
+```yaml
+dependencies:
+  - name: json
+  - name: logger
+  - name: optparse
+  - name: rdoc
+  - name: tsort
+```
+
+Note that you don't have to write the dependencies that are included in your `.gemspec`. RBS will detect the dependencies between gems, declared in `.gemspec`. `manifest.yaml` is a material for undeclared dependencies, which usually is for standard libraries.
+
+## Testing your type definition
+
+If you develop your gem using a static type checker, like [Steep](https://github.com/soutaro/steep), your type definition will be (mostly) correct and reliable. If not, we strongly recommend adding extra tests focusing on the RBS type definitions.
+
+`RBS::UnitTest` is a library to do that. `assert_send_type` is the most important assertion.
+
+```rb
+assert_send_type '(Regexp) { (String) -> String } -> String',
+                 'hello', :gsub, /hello/, &proc { "foo" }
+```
+
+It calls `String#gsub` method and confirms if given arguments and the return value has correct types.
+
+You can find examples under `test/stdlib` directory of [RBS repository](https://github.com/ruby/rbs/blob/6b3d0f976a50b3974d0bff26ea8fa9931053f38b/test/stdlib/String_test.rb).