ruby-lint 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0b345fdf9724a766a2684c0977f862cd7e408ce9
-  data.tar.gz: a6d56efba7d749595035211678c38c8a4323c94d
+  metadata.gz: dd18d2ac845d4520591324dc3491cbd5a3d9b0ca
+  data.tar.gz: b7a344031e1b300104e1331486dbc4b8903ff9c8
 SHA512:
-  metadata.gz: efe10626ab798f0d8069d5bceb3c39efb634c1afbf009490c0a01670ca2f049ddabbbf9f17f3f9a84058cb69fe14c9b42f3031da4d9211c1d8f075d3889596af
-  data.tar.gz: 14f98dd7fdf7875035021f5830da8574c0f4ab82bbbc7775a1476a26e56052dd4259ba0d67e9c8a1893e090bc5c4db3dc069e6f2ac2d0ddd4ceae06617872813
+  metadata.gz: 78ad431d97cef27b33f53842e36b46771895a3d1cef0ce8982a77245e5ce3b1c1400318ece043a24a594277eb21ab5dad6026d74473c9d1c9354a5289ddf6309
+  data.tar.gz: c6010baaeb8aec96bdaf8a00eb80c92a186be594fa20136e45a3a374749c20588a3a0dd8bac2dd659d7f911eb40cd321f28f291dd1c3dd92daf6932d7fd3234f

data/.ruby-version

@@ -1 +1 @@
-2.0
+2.1

data/.travis.yml

@@ -4,7 +4,8 @@ script: bundle exec rake travis
 rvm:
   - 1.9.3
   - 2.0.0
-  - rbx-2.2.1
+  - 2.1.0
+  - rbx-2.2
   - jruby-19mode
 
 notifications:
@@ -15,8 +16,4 @@ notifications:
       on_success: change
       on_failure: always
 
-branches:
-  only:
-    - master
-
 cache: bundler

data/Gemfile

@@ -3,8 +3,13 @@ source 'https://rubygems.org/'
 gemspec
 
 group :testing do
-  gem 'rubysl', :platform => :rbx
-  gem 'rubinius-developer_tools', :platform => :rbx
-  gem 'racc', :platform => :rbx
-  gem 'ruby-prof', :platform => :mri
+  platform :rbx do
+    gem 'rubysl'
+    gem 'rubinius-developer_tools'
+    gem 'racc'
+  end
+
+  platform :mri do
+    gem 'ruby-prof'
+  end
 end

data/MANIFEST

@@ -21,6 +21,8 @@ checksum/ruby-lint-0.9.1.gem.sha512
 checksum/ruby-lint-1.0.0.gem.sha512
 checksum/ruby-lint-1.0.0.pre.preview1.gem.sha512
 checksum/ruby-lint-1.0.1.gem.sha512
+checksum/ruby-lint-1.0.2.gem.sha512
+checksum/ruby-lint-1.0.3.gem.sha512
 doc/.gitkeep
 doc/DCO.md
 doc/architecture.md
@@ -29,9 +31,15 @@ doc/code_analysis.md
 doc/configuration.md
 doc/css/.gitkeep
 doc/css/common.css
+doc/definitions.md
 doc/graphviz/flow.dot
 doc/images/.gitkeep
 doc/images/flow.png
+gen/rails/constants.txt
+gen/rails/requires.rb
+gen/stdlib/constants.rb
+gen/stdlib/constants.txt
+gen/stdlib/requires.rb
 lib/ruby-lint.rb
 lib/ruby-lint/analysis/argument_amount.rb
 lib/ruby-lint/analysis/base.rb
@@ -40,6 +48,7 @@ lib/ruby-lint/analysis/shadowing_variables.rb
 lib/ruby-lint/analysis/undefined_methods.rb
 lib/ruby-lint/analysis/undefined_variables.rb
 lib/ruby-lint/analysis/unused_variables.rb
+lib/ruby-lint/analysis/useless_equality_checks.rb
 lib/ruby-lint/ast/builder.rb
 lib/ruby-lint/ast/node.rb
 lib/ruby-lint/benchmark/average.rb
@@ -47,14 +56,14 @@ lib/ruby-lint/cache.rb
 lib/ruby-lint/cache_entry.rb
 lib/ruby-lint/cli.rb
 lib/ruby-lint/cli/analyze.rb
-lib/ruby-lint/cli/ast.rb
 lib/ruby-lint/cli/base.rb
-lib/ruby-lint/cli/plot.rb
+lib/ruby-lint/cli/cache.rb
 lib/ruby-lint/configuration.rb
 lib/ruby-lint/constant_loader.rb
 lib/ruby-lint/constant_path.rb
 lib/ruby-lint/default_names.rb
 lib/ruby-lint/definition/constant_proxy.rb
+lib/ruby-lint/definition/registry.rb
 lib/ruby-lint/definition/ruby_method.rb
 lib/ruby-lint/definition/ruby_object.rb
 lib/ruby-lint/definition_builder/base.rb
@@ -68,12 +77,10 @@ lib/ruby-lint/definition_builder/ruby_module.rb
 lib/ruby-lint/definition_generator.rb
 lib/ruby-lint/definitions/core.rb
 lib/ruby-lint/definitions/core/abbrev.rb
-lib/ruby-lint/definitions/core/arg0.rb
 lib/ruby-lint/definitions/core/argf.rb
 lib/ruby-lint/definitions/core/argument_error.rb
 lib/ruby-lint/definitions/core/argv.rb
 lib/ruby-lint/definitions/core/array.rb
-lib/ruby-lint/definitions/core/autoload.rb
 lib/ruby-lint/definitions/core/base64.rb
 lib/ruby-lint/definitions/core/basic_object.rb
 lib/ruby-lint/definitions/core/basic_socket.rb
@@ -89,13 +96,11 @@ lib/ruby-lint/definitions/core/complex.rb
 lib/ruby-lint/definitions/core/condition_variable.rb
 lib/ruby-lint/definitions/core/config.rb
 lib/ruby-lint/definitions/core/conftest_c.rb
-lib/ruby-lint/definitions/core/continuation.rb
 lib/ruby-lint/definitions/core/coutflag.rb
 lib/ruby-lint/definitions/core/csv.rb
 lib/ruby-lint/definitions/core/data.rb
 lib/ruby-lint/definitions/core/date.rb
 lib/ruby-lint/definitions/core/date_time.rb
-lib/ruby-lint/definitions/core/default_record_separator.rb
 lib/ruby-lint/definitions/core/delegator.rb
 lib/ruby-lint/definitions/core/digest.rb
 lib/ruby-lint/definitions/core/dir.rb
@@ -118,12 +123,10 @@ lib/ruby-lint/definitions/core/export_prefix.rb
 lib/ruby-lint/definitions/core/failed_message.rb
 lib/ruby-lint/definitions/core/false.rb
 lib/ruby-lint/definitions/core/false_class.rb
-lib/ruby-lint/definitions/core/fatal_error.rb
 lib/ruby-lint/definitions/core/fcntl.rb
 lib/ruby-lint/definitions/core/fiber.rb
 lib/ruby-lint/definitions/core/fiber_error.rb
 lib/ruby-lint/definitions/core/file.rb
-lib/ruby-lint/definitions/core/file_list.rb
 lib/ruby-lint/definitions/core/file_test.rb
 lib/ruby-lint/definitions/core/file_utils.rb
 lib/ruby-lint/definitions/core/find.rb
@@ -137,7 +140,6 @@ lib/ruby-lint/definitions/core/getopt_long.rb
 lib/ruby-lint/definitions/core/gserver.rb
 lib/ruby-lint/definitions/core/hash.rb
 lib/ruby-lint/definitions/core/hdr_ext.rb
-lib/ruby-lint/definitions/core/immediate_value.rb
 lib/ruby-lint/definitions/core/index_error.rb
 lib/ruby-lint/definitions/core/install_dirs.rb
 lib/ruby-lint/definitions/core/integer.rb
@@ -163,8 +165,6 @@ lib/ruby-lint/definitions/core/marshal.rb
 lib/ruby-lint/definitions/core/match_data.rb
 lib/ruby-lint/definitions/core/math.rb
 lib/ruby-lint/definitions/core/matrix.rb
-lib/ruby-lint/definitions/core/md5.rb
-lib/ruby-lint/definitions/core/memory_segmention_error.rb
 lib/ruby-lint/definitions/core/method.rb
 lib/ruby-lint/definitions/core/module.rb
 lib/ruby-lint/definitions/core/monitor.rb
@@ -191,32 +191,23 @@ lib/ruby-lint/definitions/core/orig_libpath.rb
 lib/ruby-lint/definitions/core/outflag.rb
 lib/ruby-lint/definitions/core/pathname.rb
 lib/ruby-lint/definitions/core/pp.rb
-lib/ruby-lint/definitions/core/precision.rb
 lib/ruby-lint/definitions/core/pretty_print.rb
 lib/ruby-lint/definitions/core/prime.rb
-lib/ruby-lint/definitions/core/primitive_failure.rb
 lib/ruby-lint/definitions/core/proc.rb
 lib/ruby-lint/definitions/core/process.rb
 lib/ruby-lint/definitions/core/profiler__.rb
 lib/ruby-lint/definitions/core/pstore.rb
-lib/ruby-lint/definitions/core/psych.rb
 lib/ruby-lint/definitions/core/queue.rb
-lib/ruby-lint/definitions/core/rake.rb
-lib/ruby-lint/definitions/core/rake_file_utils.rb
-lib/ruby-lint/definitions/core/rakeversion.rb
 lib/ruby-lint/definitions/core/random.rb
 lib/ruby-lint/definitions/core/range.rb
 lib/ruby-lint/definitions/core/range_error.rb
 lib/ruby-lint/definitions/core/rational.rb
 lib/ruby-lint/definitions/core/rb_config.rb
-lib/ruby-lint/definitions/core/rdoc.rb
 lib/ruby-lint/definitions/core/readline.rb
 lib/ruby-lint/definitions/core/regexp.rb
 lib/ruby-lint/definitions/core/regexp_error.rb
 lib/ruby-lint/definitions/core/resolv.rb
-lib/ruby-lint/definitions/core/rexml.rb
 lib/ruby-lint/definitions/core/rpathflag.rb
-lib/ruby-lint/definitions/core/rss.rb
 lib/ruby-lint/definitions/core/ruby_copyright.rb
 lib/ruby-lint/definitions/core/ruby_description.rb
 lib/ruby-lint/definitions/core/ruby_engine.rb
@@ -232,7 +223,6 @@ lib/ruby-lint/definitions/core/script_error.rb
 lib/ruby-lint/definitions/core/secure_random.rb
 lib/ruby-lint/definitions/core/security_error.rb
 lib/ruby-lint/definitions/core/set.rb
-lib/ruby-lint/definitions/core/sha1.rb
 lib/ruby-lint/definitions/core/shellwords.rb
 lib/ruby-lint/definitions/core/signal.rb
 lib/ruby-lint/definitions/core/signal_exception.rb
@@ -281,8 +271,6 @@ lib/ruby-lint/definitions/core/unbound_method.rb
 lib/ruby-lint/definitions/core/universal_ints.rb
 lib/ruby-lint/definitions/core/unixserver.rb
 lib/ruby-lint/definitions/core/unixsocket.rb
-lib/ruby-lint/definitions/core/unmarshalable.rb
-lib/ruby-lint/definitions/core/unsupported_library_error.rb
 lib/ruby-lint/definitions/core/uri.rb
 lib/ruby-lint/definitions/core/vector.rb
 lib/ruby-lint/definitions/core/weak_ref.rb
@@ -291,8 +279,9 @@ lib/ruby-lint/definitions/core/xmlrpc.rb
 lib/ruby-lint/definitions/core/yaml.rb
 lib/ruby-lint/definitions/core/zero_division_error.rb
 lib/ruby-lint/definitions/core/zlib.rb
-lib/ruby-lint/definitions/global_variables.rb
-lib/ruby-lint/definitions/rails.rb
+lib/ruby-lint/definitions/gems/.gitkeep
+lib/ruby-lint/definitions/gems/devise.rb
+lib/ruby-lint/definitions/gems/nokogiri.rb
 lib/ruby-lint/definitions/rails/abstract_controller.rb
 lib/ruby-lint/definitions/rails/action_controller.rb
 lib/ruby-lint/definitions/rails/action_dispatch.rb
@@ -310,10 +299,10 @@ lib/ruby-lint/docstring/param_tag.rb
 lib/ruby-lint/docstring/parser.rb
 lib/ruby-lint/docstring/return_tag.rb
 lib/ruby-lint/extensions/string.rb
+lib/ruby-lint/file_list.rb
 lib/ruby-lint/file_loader.rb
 lib/ruby-lint/file_scanner.rb
 lib/ruby-lint/generated_constant.rb
-lib/ruby-lint/global_scope.rb
 lib/ruby-lint/inspector.rb
 lib/ruby-lint/iterator.rb
 lib/ruby-lint/method_call/alias.rb
@@ -329,8 +318,10 @@ lib/ruby-lint/parser.rb
 lib/ruby-lint/presenter/json.rb
 lib/ruby-lint/presenter/syntastic.rb
 lib/ruby-lint/presenter/text.rb
+lib/ruby-lint/rake_task.rb
 lib/ruby-lint/report.rb
 lib/ruby-lint/report/entry.rb
+lib/ruby-lint/ruby_lint.rb
 lib/ruby-lint/runner.rb
 lib/ruby-lint/template/definition.erb
 lib/ruby-lint/template/scope.rb
@@ -369,15 +360,17 @@ spec/ruby-lint/analysis/shadowing_variables_spec.rb
 spec/ruby-lint/analysis/undefined_methods_spec.rb
 spec/ruby-lint/analysis/undefined_variables_spec.rb
 spec/ruby-lint/analysis/unused_variables_spec.rb
+spec/ruby-lint/analysis/useless_equality_checks_spec.rb
 spec/ruby-lint/ast/node_spec.rb
 spec/ruby-lint/cache_entry_spec.rb
 spec/ruby-lint/cache_spec.rb
 spec/ruby-lint/cli/analyze_spec.rb
-spec/ruby-lint/cli/ast_spec.rb
 spec/ruby-lint/configuration_spec.rb
+spec/ruby-lint/constant_loader_spec.rb
 spec/ruby-lint/constant_path.rb
 spec/ruby-lint/definition/constant_proxy_spec.rb
 spec/ruby-lint/definition/dsl_spec.rb
+spec/ruby-lint/definition/registry_spec.rb
 spec/ruby-lint/definition/ruby_method_spec.rb
 spec/ruby-lint/definition/ruby_object_spec.rb
 spec/ruby-lint/definition_builder/primitive_spec.rb
@@ -386,15 +379,21 @@ spec/ruby-lint/definition_builder/ruby_method_spec.rb
 spec/ruby-lint/definition_builder/ruby_module_spec.rb
 spec/ruby-lint/definitions/argv_spec.rb
 spec/ruby-lint/definitions/env_spec.rb
+spec/ruby-lint/definitions/file_spec.rb
+spec/ruby-lint/definitions/fixnum_spec.rb
 spec/ruby-lint/definitions/io_spec.rb
+spec/ruby-lint/definitions/kernel_spec.rb
+spec/ruby-lint/definitions/range_spec.rb
+spec/ruby-lint/definitions/string_spec.rb
 spec/ruby-lint/docstring/mapping.rb
 spec/ruby-lint/docstring/parser_spec.rb
 spec/ruby-lint/extensions/string_spec.rb
+spec/ruby-lint/file_list_spec.rb
 spec/ruby-lint/file_loader_spec.rb
 spec/ruby-lint/file_scanner_spec.rb
 spec/ruby-lint/inspector_spec.rb
 spec/ruby-lint/iterator_spec.rb
-spec/ruby-lint/method_call/assign_member_spec.rb
+spec/ruby-lint/method_call/.gitkeep
 spec/ruby-lint/nested_stack_spec.rb
 spec/ruby-lint/node_hash_spec.rb
 spec/ruby-lint/parser_spec.rb
@@ -404,6 +403,7 @@ spec/ruby-lint/presenter/text_spec.rb
 spec/ruby-lint/report/entry_spec.rb
 spec/ruby-lint/report_spec.rb
 spec/ruby-lint/runner_spec.rb
+spec/ruby-lint/variable_predicates_spec.rb
 spec/ruby-lint/virtual_machine/alias_spec.rb
 spec/ruby-lint/virtual_machine/assignments/arrays_spec.rb
 spec/ruby-lint/virtual_machine/assignments/assignment_arguments_spec.rb
@@ -433,16 +433,20 @@ spec/ruby-lint/virtual_machine/interpolation_spec.rb
 spec/ruby-lint/virtual_machine/location_spec.rb
 spec/ruby-lint/virtual_machine/method_call_tracking_spec.rb
 spec/ruby-lint/virtual_machine/methods/attr_spec.rb
+spec/ruby-lint/virtual_machine/methods/calls_spec.rb
 spec/ruby-lint/virtual_machine/methods/define_method_spec.rb
 spec/ruby-lint/virtual_machine/methods/defining_spec.rb
 spec/ruby-lint/virtual_machine/methods/docstrings_spec.rb
 spec/ruby-lint/virtual_machine/methods/exporting_spec.rb
+spec/ruby-lint/virtual_machine/methods/kernel_spec.rb
 spec/ruby-lint/virtual_machine/methods/parameters_spec.rb
 spec/ruby-lint/virtual_machine/methods/patching_spec.rb
 spec/ruby-lint/virtual_machine/methods/scoping_spec.rb
+spec/ruby-lint/virtual_machine/methods/square_bracket_spec.rb
 spec/ruby-lint/virtual_machine/methods/visibility_spec.rb
 spec/ruby-lint/virtual_machine/modules_spec.rb
 spec/ruby-lint/virtual_machine/reference_amount_spec.rb
+spec/ruby-lint/virtual_machine/self_spec.rb
 spec/ruby-lint/virtual_machine/unused_spec.rb
 spec/spec_helper.rb
 spec/support/building.rb

data/README.md

@@ -4,10 +4,21 @@
 [![Coverage Status](https://coveralls.io/repos/YorickPeterse/ruby-lint/badge.png?branch=master)](https://coveralls.io/r/YorickPeterse/ruby-lint)
 [![Code Climate](https://codeclimate.com/github/YorickPeterse/ruby-lint.png)](https://codeclimate.com/github/YorickPeterse/ruby-lint)
 
-ruby-lint is a linter and static code analysis tool for Ruby. It is inspired by
-similar tools such as jshint, flake8 and similar tools. ruby-lint primarily
-focuses on logic related errors such as the use of non existing variables
-instead of focusing on semantics (e.g. the amount of characters per line).
+ruby-lint is a static code analysis tool for Ruby. It is inspired by tools such
+as jshint, flake8 and similar tools. ruby-lint primarily focuses on logic
+related errors such as the use of non existing variables instead of focusing on
+semantics (e.g. the amount of characters per line).
+
+The features of ruby-lint include but are not limited to the detection of
+unused variables, the use of undefined methods and method calls with invalid
+argument amounts and more. More in-depth analysis will be added over time.
+
+The aim of ruby-lint is to provide analysis that is as accurate as possible.
+However, due to the dynamic nature of Ruby and the sheer amount of meta-magic
+in third-party code there will at times be false positives. Analysis can be
+improved by documenting your code using [YARD][yard], in particular the
+`@param` and `@return` tags are used by ruby-lint to obtain extra information
+when processing methods.
 
 ## Requirements
 
@@ -16,7 +27,7 @@ instead of focusing on semantics (e.g. the amount of characters per line).
 
 The following Ruby implementations/versions are officially supported:
 
-* MRI 1.9.3 and newer
+* MRI 1.9.3, 2.0 or 2.1
 * Rubinius 2.0 and newer
 * Jruby 1.7 and newer
 
@@ -123,6 +134,7 @@ In the past Gems were also signed using PGP, this is no longer the case.
 * {file:architecture Architecture}
 * {file:code\_analysis Code Analysis}
 * {file:configuration Configuration}
+* {file:definitions Definitions}
 
 ## License
 
@@ -133,3 +145,4 @@ in the root directory of this repository.
 [syntastic]: https://github.com/scrooloose/syntastic
 [flycheck]: https://github.com/flycheck/flycheck/
 [rubocop]: https://github.com/bbatsov/rubocop
+[yard]: http://yardoc.org/

data/Rakefile

@@ -1,6 +1,5 @@
-require File.expand_path('../lib/ruby-lint/extensions/string', __FILE__)
-require File.expand_path('../lib/ruby-lint/inspector', __FILE__)
-require File.expand_path('../lib/ruby-lint/definition_generator', __FILE__)
+require_relative 'lib/ruby-lint/definition_generator'
+require_relative 'lib/ruby-lint/rake_task'
 
 require 'yaml'
 require 'bundler/gem_tasks'
@@ -8,6 +7,11 @@ require 'digest/sha2'
 require 'coveralls/rake/task'
 require 'rake/clean'
 
+RubyLint::RakeTask.new do |task|
+  task.name  = 'lint'
+  task.files = ['./lib/ruby-lint']
+end
+
 Coveralls::RakeTask.new
 
 GEMSPEC = Gem::Specification.load('ruby-lint.gemspec')

data/checksum/ruby-lint-1.0.2.gem.sha512

@@ -0,0 +1 @@
+01bdfe10f10950d2035dc1a0289e0cf1b6f40a0b23fead3ee1f39391e309ed00972bdc0a2b35859539660ebb1a2cc5a222f9eded6d511a28daa32fdeb9829786

data/checksum/ruby-lint-1.0.3.gem.sha512

@@ -0,0 +1 @@
+dc93aa3a5f196b8badbab5c06975e7da6710508e2f6efebf16f063413d4f1d80d8f02897c0aced4a7593e16d1f2f53465a3be9ff16d0b6b084086ec6a169aa1a

data/doc/changelog.md

@@ -5,6 +5,46 @@ This document contains a short summary of the various releases of ruby-lint.
 For a full list of commits included in each release see the corresponding Git
 tags (named after the versions).
 
+## 1.1.0 - 2014-02-02
+
+This release changes the way the definitions system works so that it no longer
+stores a set of global definition objects. Instead "templates" (so to speak)
+are provided which are applied to individual `RubyLint::VirtualMachine`
+instances. This makes it much easier to analyze code that patches core classes
+such as `String` or `Fixnum`.
+
+There have also been various other, smaller changes. The ones worth mentioning
+as following:
+
+* A new analysis class, UselessEqualityChecks, has been added. This class adds
+  warnings for expressions such as `"foo" == true`.
+* A Rake task class has been added, making it easier to integrate ruby-lint in
+  a Rakefile.
+* The CLI has been cleaned up and the `plot` and `ast` commands have been
+  removed. A new command, `cache` has been introduced to manage ruby-lint cache
+  files more easily.
+* A bug has been fixed that would prevent ruby-lint from properly loading files
+  from multiple directories, see Git commit
+  `292bb2b73aa6adfdc750fb846884025afc841393`.
+* Definitions have been added for Devise and Nokogiri.
+* Most built-in definitions have been re-generated.
+* Definitions system has been overhauled to no longer use a global state and a
+  complex data copying system. Instead the definitions are applied to every
+  individual `RubyLint::VirtualMachine` instance.
+* Updated the version of the parser Gem to use.
+
+The following bugs/issues have been resolved in this release:
+
+* https://github.com/YorickPeterse/ruby-lint/issues/89
+* https://github.com/YorickPeterse/ruby-lint/issues/85
+* https://github.com/YorickPeterse/ruby-lint/issues/91
+* https://github.com/YorickPeterse/ruby-lint/issues/92
+* https://github.com/YorickPeterse/ruby-lint/issues/93
+* https://github.com/YorickPeterse/ruby-lint/issues/94
+* https://github.com/YorickPeterse/ruby-lint/issues/100
+* https://github.com/YorickPeterse/ruby-lint/issues/101
+* https://github.com/YorickPeterse/ruby-lint/issues/102
+
 ## 1.0.3 - 2013-12-23
 
 * `self` is now defined as a class and instance method to ensure that the right

data/doc/definitions.md

@@ -0,0 +1,182 @@
+# @title Definitions
+# Definitions
+
+To obtain extra information used in the analysis process ruby-lint uses a set
+of so called "definitions". These definitions describe constants and their
+methods and the associated arguments of said methods. The definitions can be
+created using a basic DSL. Typically end users don't have to write these
+manually as ruby-lint comes with a set of Rake tasks to ease the process of
+creating these definitions. However, manual tweaking might be required in rare
+cases.
+
+## Rationale
+
+The definitions exist for 3 reasons:
+
+1. Both MRI and JRuby provide insufficient runtime reflection on method
+   arguments (more on this below), a rather crucial aspect in performing
+   meaningful analysis.
+2. Relying on the current runtime for extra information means that users will
+   have to load all their used libraries into a ruby-lint session. This will
+   often result in degraded performance, in particular startup times will
+   increase.
+3. It's not possible to, during runtime, determine the return type(s) of a
+   method. This can only be done by either relying on source documentation or
+   by other manual means.
+
+These 3 topics are described in detail below.
+
+### Argument Reflection
+
+Ruby as a language provides the means to, during runtime, find out what
+arguments a method has, their types and names. For example, consider the
+following code:
+
+    def example(a, b)
+      return a + b
+    end
+
+We can obtain the arguments list by running the following code:
+
+    method(:example).parameters
+
+This would result in the following value being returned:
+
+    [[:req, :a], [:req, :b]]
+
+Using this we can see that the method takes two required arguments, `a` and
+`b`.
+
+Although this works great for methods that are defined in Ruby itself this does
+not work reliably for methods defined in C (in case of MRI) or in Java (in case
+of JRuby).
+
+As an example, lets take a look at `String#gsub`. The RDoc documentation of
+this method states the following about its arguments:
+
+    = String#gsub
+
+    (from ruby core)
+    ------------------------------------------------------------------------------
+      str.gsub(pattern, replacement)       -> new_str
+      str.gsub(pattern, hash)              -> new_str
+      str.gsub(pattern) {|match| block }   -> new_str
+      str.gsub(pattern)                    -> enumerator
+
+This states that the method takes 1 required argument (`pattern`), one optional
+argument (`replacement` / `hash`) and a block. However, when we inspect the
+arguments list of this method in MRI we get different results:
+
+    String.instance_method(:gsub).parameters # => [[:rest]]
+
+This would indicate that the method instead takes a single rest argument. This
+however is simply false as calling the method without any arguments (rest
+arguments being optional) results in an argument error:
+
+    'foo'.gsub # => ArgumentError: wrong number of arguments (0 for 1..2)
+
+This is due to the fact that `String#gsub` method (and many other methods in
+MRI) are defined in C. Since the C API doesn't expose proper systems for
+exposing the argument amounts/types this information is lost.
+
+JRuby is also affected by this though at present it's unclear to me if this is
+intentional (in order to mimic MRI's broken behaviour) or a side effect.
+Currently Rubinius is the only Ruby implementation that I know of that does not
+suffer from this problem, largely due to it actually using Ruby for a large
+amount of its core.
+
+The above problem also affects every Ruby C extension such as Nokogiri and many
+others.
+
+This particular lack of information is problematic for ruby-lint as it means
+that it can not perform meaningful analysis when it relies on the current
+runtime. After all, the accuracy of the analysis process would change depending
+on the Ruby implementation leading to confusing behaviour and false positives.
+
+To combat this ruby-lint doesn't use the current runtime for obtaining method
+information. Instead it uses definitions that are pre-generated using Rubinius.
+However, even on Rubinius the accuracy of these definitions will vary for C
+extensions depending on how much these extensions define in C opposed to Ruby.
+
+### Degraded Performance
+
+The second reason for not using the current runtime is that by doing so users
+would be required to load their libraries into a ruby-lint session. For
+example, for a Rails project this means loading all of Rails, all the used
+Gems, custom code defined in the `app/` directory and so forth. Doing so will
+increase the startup time of ruby-lint up to a point where it becomes downright
+annoying.
+
+To give an example, merely loading Rails using `require 'rails/all'` will add
+around 500 milliseconds to the startup time. Add a few more Gems such as
+Devise, Mongoid and what not and you'll quickly end up having to wait seconds
+for ruby-lint to start up (or any other Ruby program for that matter).
+
+As a result of this it was decided that this was less than optimal, which in
+turn was another reason to use pre-generated definitions.
+
+### Return Types
+
+Due to Ruby being dynamically typed it's impossible to deduce the return type
+of a method. As a result of this ruby-lint would not be able to figure out what
+`SomeClass.new` would return. This means that for code such as
+`SomeClass.new.foo` ruby-lint would have no other choice but to completely
+ignore it.
+
+ruby-lint tries to work around this using two methods:
+
+1. Using YARD documentation (in particular the `@return` and `@param` tags) to
+   obtain more information during runtime.
+2. Using pre-generated definitions that specify return types such as those for
+   the `new` and `initialize` methods.
+
+This means that ruby-lint is capable of understanding that `String.new` returns
+an instance of `String`. ruby-lint makes the assumption that the class method
+`new` returns an instance of the constant it is defined in, unless the method
+is explicitly overwritten.
+
+## Generating Definitions
+
+In most cases one does not need to write these definitions manually, instead
+they are generated using a set of Rake tasks. For best results it's recommended
+to use Rubinius in case you're generating definitions for the Ruby standard
+library.
+
+Assuming you have a local copy of ruby-lint you can generate your definitions
+by running the following Rake task:
+
+    rake -r YOUR_GEM generate:definitions[CONSTANT,lib/ruby-lint/definitions/gems]
+
+Here `YOUR_GEM` would be the name of your Gem, `CONSTANT` would be the
+top-level constant. For example, to generate the definitions for Devise you'd
+run the following:
+
+    rake -r devise generate:definitions[Devise,lib/ruby-lint/definitions/gems]
+
+If you are comfortable with the resulting definitions you can submit a pull
+request and I'll take a look at it. I prefer for the definitions to be included
+with ruby-lint itself as this makes it easier to maintain and distribute them
+without requiring users to install a bunch of extra Gems.
+
+## Using Definitions
+
+When processing source code ruby-lint will try to automatically load
+definitions where needed. For this to work the definitions should be available
+in the load path defined in {RubyLint::Definition::Registry#load\_path}. By
+default the following directories are searched in for definitions:
+
+* lib/ruby-lint/definitions/core
+* lib/ruby-lint/definitions/rails
+* lib/ruby-lint/definitions/gems
+
+There should be no need to add extra paths to this list.
+
+Definitions are looked up based on the top-level constant referenced in a file.
+For example, of ruby-lint bumps into the constant path `Foo::Bar::Baz` it will
+try to look for a file called `foo.rb` in the above directories. It is expected
+that if this file exists it defines the `Foo` constant (and its child
+constants).
+
+The process of loading definitions is handled by
+{RubyLint::Definition::Registry#load} and
+{RubyLint::ConstantLoader#load\_constant}.