Add docs

Author: soutaro

README.md

@@ -76,6 +76,12 @@ $ ruby-signature -r set list
 $ ruby-signature -I sig list
 ```
 
+## Guides
+
+- [Writing signatures guide](doc/sigs.md)
+- [Stdlib signatures guide](doc/stdlib.md)
+- [Syntax](doc/syntax.md)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

doc/sigs.md

@@ -0,0 +1,142 @@
+# Writing Signatures Guide
+
+You can write the signature of your applications and libraries.
+Signature of your Ruby program would help:
+
+1. Understanding the code structure
+2. Finding APIs
+
+And if you ship your gem with signature, the gem users can type check their applications!
+
+## Writing signatures
+
+You first need to write your program's signature.
+See [syntax guide](syntax.md).
+
+## Testing signatures
+
+When you finish writing signature, you may want to test the signature.
+ruby-signature provides a feature to test your signature.
+
+```
+$ RBS_TEST_TARGET='Foo::*' bundle exec ruby -r ruby/signature/test/setup test/foo_test.rb
+```
+
+The test installs instrumentations to spy the method calls and check if arguments/return values are correct with respect to the type of the method in signature.
+If errors are reported by the test, you will fix the signature.
+You will be sure that you ship a correct signature finally.
+
+The instrumentations are implemneted using `Module#prepend`.
+It defines a module with same name of methods, which asserts the type of arguments/return values and calls `super`.
+
+## Type errors
+
+If the test detects type errors, it will print error messages.
+
+### ArgumentTypeError, BlockArgumentTypeError
+
+The message means there is an unexpected type of argument or block argument.
+
+```
+ERROR -- : [Kaigi::Speaker.new] ArgumentTypeError: expected `::String` (email) but given `:"matsumoto@soutaro.com"`
+```
+
+### ArgumentError, BlockArgumentError
+
+The message means there is an unexpected argument or missing argument.
+
+```
+[Kaigi::Speaker.new] ArgumentError: expected method type (size: ::Symbol, email: ::String, name: ::String) -> ::Kaigi::Speaker
+```
+
+### ReturnTypeError, BlockReturnTypeError
+
+The message means the return value from method or block is incorrect.
+
+```
+ERROR -- : [Kaigi::Conference#each_speaker] ReturnTypeError: expected `self` but returns `[#<Kaigi::Speaker:0x00007fb2b249e5a0 @name="Soutaro Matsumoto", @email=:"matsumoto@soutaro.com">]`
+```
+
+### UnexpectedBlockError, MissingBlockError
+
+The errors are reported when required block is not given or unused block is given.
+
+```
+ERROR -- : [Kaigi::Conference#speakers] UnexpectedBlockError: unexpected block is given for `() -> ::Array[::Kaigi::Speaker]`
+```
+
+### UnresolvedOverloadingError
+
+The error means there is a type error on overloaded methods.
+The `ruby-signature` test framework tries to the best error message for overloaded methods too, but it reports the `UnresolvedOverloadingError` when it fails.
+
+## Setting up the test
+
+The design of the signature testing aims to be non-intrusive. The setup is done in two steps:
+
+1. Loading the testing library
+2. Setting up the test through environment variables
+
+### Loading the library
+
+You need to require `ruby/signature/test/setup` for signature testing.
+You can do it using `-r` option through command line argument or the `RUBYOPT` environment variable.
+
+```
+$ ruby -r ruby/signature/test/setup run_tests.rb
+$ RUBYOPT='-rruby/signature/test/setup' rake test
+```
+
+When you are using Bundler, you may need to require `bundler/setup` explicitly.
+
+```
+$ RUBYOPT='-rbundler/setup -rruby/signature/test/setup' bundle exec rake test
+```
+
+### Environment variables
+
+You need to specify `RBS_TEST_TARGET` to run the test, and you can customize the test with the following environment variables.
+
+- `RBS_TEST_SKIP` (optional)
+- `RBS_TEST_OPT` (optional)
+- `RBS_TEST_LOGLEVEL` (optional)
+
+`RBS_TEST_TARGET` is to specify the classes you want to test. `RBS_TEST_TARGET` can contain comma-separated class name pattern, which is one of an exact class name or with wildcard `*`.
+
+- `RBS_TEST_TARGET=Foo::Bar,Foo::Baz` comma separated exact class names
+- `RBS_TEST_TARGET=Foo::*` using wildcard
+
+`RBS_TEST_SKIP` is to skip some of the classes which matches with `RBS_TEST_TARGET`.
+
+`RBS_TEST_OPT` is to pass the options for ruby signature handling.
+You may need to specify `-r` or `-I` to load signatures.
+The default is `-I sig`.
+
+```
+RBS_TEST_OPT='-r set -r pathname -I sig'
+```
+
+`RBS_TEST_LOGLEVEL` can be used to configure log level. Defaults to `info`.
+
+So, a typical command line to start the test would look like the following:
+
+```
+$ RBS_TEST_LOGLEVEL=error \
+  RBS_TEST_TARGET='Kaigi::*' \
+  RBS_TEST_SKIP='Kaigi::MonkeyPatch' \
+  RBS_TEST_OPT='-rset -rpathname -Isig -Iprivate' \
+  RUBY_OPT='-rbundler/setup -rruby/signature/test/setup' \
+  bundle exec rake test
+```
+
+## Testing tips
+
+### Skipping a method
+
+You can skip installing the instrumentation per-method basis using `rbs:test:skip` annotation.
+
+```
+class String
+  %a{rbs:test:skip} def =~: (Regexp) -> Integer?
+end
+```

doc/stdlib.md

@@ -0,0 +1,52 @@
+# Stdlib Signatures Guide
+
+This is a guide for contributing to `ruby-signature` by writing/revising stdlib signatures.
+
+## Signatures
+
+Signatures for standard libraries are located in `stdlib` directory. `stdlib/builtin` is for builtin libraries. Other libraries have directories like `stdlibt/set` or `stdlib/pathname`.
+
+To write signatures see [syntax guide](`syntax.md`).
+
+## Testing
+
+We support writing tests for stdlib signatures.
+
+### Writing tests
+
+Put the test scripts in `test/stdlib` directory with `[class_name]_test.rb`, like `String_test.rb` and `File_test.rb`.
+The test scripts would look like the following:
+
+```rb
+class StringTest < StdlibTest
+  target String
+  using hook.refinement
+
+  def test_gsub
+    s = "string"
+    s.gsub(/./, "")
+    s.gsub("a", "b")
+    s.gsub(/./) {|x| "" }
+    s.gsub(/./, {"foo" => "bar"})
+    s.gsub(/./)
+    s.gsub("")
+  end
+end
+```
+
+You need two method calls, `target` and `using`.
+`target` method call tells which class is the subject of the class.
+`using hook.refinement` installs a special instrumentation for stdlib, based on refinements.
+And you write the sample programs which calls all of the patterns of overloads.
+
+Note that the instrumentation is based on refinmenets and you need to write all method calls in the unit class definitions.
+If the execution of the program escape from the class definition, the instrumentation is disabled and no check will be done.
+
+### Running tests
+
+You can run the test with:
+
+```
+$ bundle exec ruby bin/test_runner.rb              # Run all tests
+$ bundle exec ruby bin/test_runner.rb String Hash  # Run specific tests
+```