'
+
+Finished in 0.00284 seconds (files took 0.28815 seconds to load)
+1 example, 1 failure
+
+Failed examples:
+
+rspec ./reek-integration-spec.rb:6 # Reek Integration works with reek
+```
+
+## The matchers explained
+
+### `reek`
+
+A very generic matcher that basically just tells you if something reeks, but not after what exactly.
+See the "Quickstart" example from above.
+
+### `reek_of`
+
+Checks the target source code for instances of "smell category"
+and returns true only if it can find one of them that matches.
+
+Remember that this includes our "smell types" as well. So it could be the
+"smell type" UtilityFunction, which is represented as a concrete class
+in reek but it could also be "Duplication" which is a "smell categgory".
+
+In theory you could pass many different types of input here:
+ - :UtilityFunction
+ - "UtilityFunction"
+ - UtilityFunction (this works in our specs because we tend to do "include Reek:Smells")
+ - Reek::Smells::UtilityFunction (the right way if you really want to pass a class)
+ - "Duplication" or :Duplication which is an abstract "smell category"
+
+It is recommended to pass this as a symbol like :UtilityFunction. However we don't
+enforce this.
+
+Additionally you can be more specific and pass in "smell_details" you
+want to check for as well e.g. "name" or "count" (see the examples below).
+The parameters you can check for are depending on the smell you are checking for.
+For instance "count" doesn't make sense everywhere whereas "name" does in most cases.
+If you pass in a parameter that doesn't exist (e.g. you make a typo like "namme") reek will
+raise an ArgumentError to give you a hint that you passed something that doesn't make
+much sense.
+
+So in a nutshell `reek_of` takes the following two arguments:
+
+- smell_category - The "smell category" or "smell_type" we check for.
+- smells_details - A hash containing "smell warning" parameters
+
+**Examples**
+
+ Without smell_details:
+
+```Ruby
+ reek_of(:FeatureEnvy)
+ reek_of(Reek::Smells::UtilityFunction)
+```
+
+With smell_details:
+
+```Ruby
+ reek_of(UncommunicativeParameterName, name: 'x2')
+ reek_of(DataClump, count: 3)
+```
+
+**Examples from a real spec**
+
+```Ruby
+ expect(src).to reek_of(Reek::Smells::DuplicateMethodCall, name: '@other.thing')
+```
+
+### reek_only_of
+
+See the documentaton for `reek_of`.
+
+**Notable differences to reek_of:**
+
+1.) `reek_of` doesn't mind if there are other smells of a different category. "reek_only_of" will fail in that case.
+
+2.) `reek_only_of` doesn't support the additional smell_details hash.
\ No newline at end of file
diff --git a/docs/Rake-Task.md b/docs/Rake-Task.md
new file mode 100644
index 000000000..707e03bd2
--- /dev/null
+++ b/docs/Rake-Task.md
@@ -0,0 +1,58 @@
+# Rake Task
+
+## Introduction
+
+`reek` provides a Rake task that runs `reek` on a set of source files. In its most simple form you just include something like that in your Rakefile:
+
+```Ruby
+require 'reek/rake/task'
+
+Reek::Rake::Task.new do |t|
+ t.fail_on_error = false
+end
+```
+
+In its most simple form, that's it.
+
+When you now run:
+
+```Bash
+rake -T
+```
+
+you should see
+
+```Bash
+rake reek # Check for code smells
+```
+
+## Configuration via task
+
+An more sophisticated rake task that would make use of all available configuration options could look like this:
+
+```Ruby
+Reek::Rake::Task.new do |t|
+ t.name = 'custom_rake' # Whatever name you want. Defaults to "reek".
+ t.config_file = 'config/config.reek' # Defaults to nothing.
+ t.source_files = 'vendor/**/*.rb' # Glob pattern to match source files. Defaults to lib/**/*.rb
+ t.reek_opts = '-U' # Defaults to ''. You can pass all the options here in that are shown by "reek -h"
+ t.fail_on_error = false # Defaults to true
+ t.verbose = true # Defaults to false
+end
+```
+
+## Configuration via environment variables
+
+You can overwrite the following attributes by environment variables:
+
+- "reek_opts" by using REEK_OPTS
+- "config_file" by using REEK_CFG
+- "source_files" by using REEK_SRC
+
+An example rake call using environment variables could look like this:
+
+```Bash
+REEK_CFG="config/custom.reek" REEK_OPTS="-s" rake reek
+```
+
+See also: [Reek-Driven-Development](Reek-Driven-Development.md)
\ No newline at end of file
diff --git a/docs/Reek-Driven-Development.md b/docs/Reek-Driven-Development.md
new file mode 100644
index 000000000..a55bee6ba
--- /dev/null
+++ b/docs/Reek-Driven-Development.md
@@ -0,0 +1,45 @@
+# Reek Driven Development
+
+## rake
+
+One way to drive quality into your code from the very beginning of a project is to run `reek` as a part of your testing process. For example, you could do that by adding a [Rake Task](Rake-Task.md) to your rakefile, which will make it easy to run `reek` on all your source files whenever you need to.
+
+```Ruby
+require 'reek/rake/task'
+
+Reek::Rake::Task.new do |t|
+ t.fail_on_error = true
+ t.verbose = false
+ t.source_files = 'lib/**/*.rb'
+end
+```
+
+Now the command `reek` will run `reek` on your source code (and in this case, it fails if it finds any smells). For more detailed information about `reek`'s integration with Rake, see [Rake Task](Rake-Task.md) in this wiki.
+
+## reek/spec
+
+But there's another way; a much more effective "Reek-driven" approach: add `reek` expectations directly into your Rspec specs. Here's an example taken directly from `reek`'s own source code:
+
+```Ruby
+it 'contains no code smells' do
+ Dir['lib/**/*.rb'].should_not reek
+end
+```
+
+By requiring "reek/spec":http://reek.rubyforge.org/rdoc/classes/Reek/Spec.html you gain access to the `reek` matcher, which returns true if and only if `reek` finds smells in your code. And if the test fails, the matcher produces an error message that includes details of all the smells it found.
+
+Note: if you're on ruby 1.9 and RSpec2 you should include Reek::Spec in the configuration block like so,
+
+```Ruby
+RSpec.configure do |c|
+ c.include(Reek::Spec)
+end
+```
+
+## assert
+
+If you're not yet into BDD with Rspec, you can still gain the benefits of Reek-driven development using assertions:
+
+```Ruby
+assert !Dir['lib/**/*.rb'].to_source.smelly?
+```
diff --git a/docs/Repeated-Conditional.md b/docs/Repeated-Conditional.md
new file mode 100644
index 000000000..314254e42
--- /dev/null
+++ b/docs/Repeated-Conditional.md
@@ -0,0 +1,44 @@
+# Repeated Conditional
+
+## Introduction
+
+`Repeated Conditional` is a special case of [Simulated Polymorphism](Simulated-Polymorphism.md). Basically it means you are checking the same value throughout a single class and take decisions based on this.
+
+## Example
+
+Given
+
+```Ruby
+class RepeatedConditionals
+ attr_accessor :switch
+
+ def repeat_1
+ puts "Repeat 1!" if switch
+ end
+
+ def repeat_2
+ puts "Repeat 2!" if switch
+ end
+
+ def repeat_3
+ puts "Repeat 3!" if switch
+ end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+test.rb -- 4 warnings:
+ [5, 9, 13]:RepeatedConditionals tests switch at least 3 times (RepeatedConditional)
+```
+
+If you get this warning then you are probably not using the right abstraction or even more probable, missing an additional abstraction.
+
+## Configuration
+
+`reek`'s `Repeated Conditional` detector offers the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option | Value | Effect |
+| ---------------|-------------|---------|
+| `max_ifs` | integer | The maximum number of identical conditional tests permitted before Reek raises a warning. Defaults to 2. |
diff --git a/docs/Simulated-Polymorphism.md b/docs/Simulated-Polymorphism.md
new file mode 100644
index 000000000..bd12e5fd3
--- /dev/null
+++ b/docs/Simulated-Polymorphism.md
@@ -0,0 +1,16 @@
+# Simulated Polymorphism
+
+## Introduction
+
+Simulated Polymorphism occurs when
+
+* code uses a case statement (especially on a type field);
+* or code has several if statements in a row (especially if they're comparing against the same value);
+* or code uses instance_of?, kind_of?, is_a?, or === to decide what type it's working with;
+* or multiple conditionals in different places test the same value.
+
+Conditional code is hard to read and understand, because the reader must hold more state in his head. When the same value is tested in multiple places throughout an application, any change to the set of possible values will require many methods and classes to change. Tests for the type of an object may indicate that the abstraction represented by that type is not completely defined (or understood).
+
+## Current Support in reek
+
+`reek` checks for [Repeated Conditional](Repeated-Conditional.md) and for [Nil Check](Nil-Check.md).
diff --git a/docs/Smell-Suppression.md b/docs/Smell-Suppression.md
new file mode 100644
index 000000000..893f23c90
--- /dev/null
+++ b/docs/Smell-Suppression.md
@@ -0,0 +1,32 @@
+## Introduction
+
+In some cases, it might be necessary to suppress one or more of `reek`'s smell warnings for a particular method or class.
+
+Possible reasons for this could be:
+
+* The code is outside of your control and you can't fix it
+* `reek` is not the police. You might have legit reasons why your source code is good as it is.
+
+## How to disable smell detection
+
+First and foremost, there are the [Basic Smell Options](Basic-Smell-Options.md) you can use.
+
+Besides from that, you can use special comments, like so:
+
+```ruby
+# This method smells of :reek:NestedIterators
+def smelly_method foo
+ foo.each {|bar| bar.each {|baz| baz.qux}}
+end
+```
+
+The method `smelly_method` will not be reported. The general pattern is to put the string ':reek:', followed by the smell class, in a comment before the method or class.
+
+It is also possible to specify options for a particular smell detector, like so:
+
+```ruby
+# :reek:LongParameterList: { max_params: 4 }
+def many_parameters_it_has foo, bar, baz, qux
+ # ...
+end
+```
diff --git a/docs/Too-Many-Instance-Variables.md b/docs/Too-Many-Instance-Variables.md
new file mode 100644
index 000000000..f8bd72e77
--- /dev/null
+++ b/docs/Too-Many-Instance-Variables.md
@@ -0,0 +1,43 @@
+## Introduction
+
+`Too Many Instance Variables` is a special case of `LargeClass`.
+
+## Example
+
+Given this configuration
+
+```yaml
+TooManyInstanceVariables:
+ max_instance_variables: 3
+```
+
+and this code:
+
+```Ruby
+class TooManyInstanceVariables
+ def initialize
+ @arg_1 = :dummy
+ @arg_2 = :dummy
+ @arg_3 = :dummy
+ @arg_4 = :dummy
+ end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+test.rb -- 5 warnings:
+ [1]:TooManyInstanceVariables has at least 4 instance variables (TooManyInstanceVariables)
+```
+## Current Support in `reek`
+
+`reek` only counts the instance variables you use explicitly like in the example above. Class macros like `attr_accessor` are disregarded.
+
+## Configuration
+
+`reek`'s `Too Many Instance Variables` detector offers the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option | Value | Effect |
+| ---------------|-------------|---------|
+| max_instance_variables | integer | The maximum number of instance variables that are permitted. Defaults to 9 |
diff --git a/docs/Too-Many-Methods.md b/docs/Too-Many-Methods.md
new file mode 100644
index 000000000..b4c46483d
--- /dev/null
+++ b/docs/Too-Many-Methods.md
@@ -0,0 +1,55 @@
+## Introduction
+
+`Too Many Methods` is a special case of `LargeClass`.
+
+## Example
+
+Given this configuration
+
+```yaml
+TooManyMethods:
+ max_methods: 3
+```
+
+and this code:
+
+```Ruby
+class TooManyMethods
+ def one; end
+ def two; end
+ def three; end
+ def four; end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+test.rb -- 1 warning:
+ [1]:TooManyMethods has at least 4 methods (TooManyMethods)
+```
+## Current Support in `reek`
+
+`reek` counts all the methods it can find in a `class` - instance *and* class methods. So given `max_methods` from above is 4, this:
+
+```Ruby
+class TooManyMethods
+ class << self
+ def one; end
+ def two; end
+ end
+
+ def three; end
+ def four; end
+end
+```
+
+would cause reek to emit the same warning as in the example above.
+
+## Configuration
+
+`reek`'s `Too Many Methods` detector offers the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option | Value | Effect |
+| ---------------|-------------|---------|
+| max_methods | integer | The maximum number of methods that are permitted. Defaults to 25 |
diff --git a/docs/Too-Many-Statements.md b/docs/Too-Many-Statements.md
new file mode 100644
index 000000000..65654f393
--- /dev/null
+++ b/docs/Too-Many-Statements.md
@@ -0,0 +1,50 @@
+# Too Many Statements
+
+## Introduction
+
+A method with `Too Many Statements` is any method that has a large number of lines.
+
+## Current Support in Reek
+
+`Too Many Statements` warns about any method that has more than 5 statements. `reek`'s smell detector for `Too Many Statements` counts +1 for every simple statement in a method and +1 for every statement within a control structure (`if`, `else`, `case`, `when`, `for`, `while`, `until`, `begin`, `rescue`) but it doesn't count the control structure itself.
+
+So the following method would score +6 in Reek's statement-counting algorithm:
+
+```Ruby
+def parse(arg, argv, &error)
+ if !(val = arg) and (argv.empty? or /\A-/ =~ (val = argv[0]))
+ return nil, block, nil # +1
+ end
+ opt = (val = parse_arg(val, &error))[1] # +2
+ val = conv_arg(*val) # +3
+ if opt and !arg
+ argv.shift # +4
+ else
+ val[0] = nil # +5
+ end
+ val # +6
+end
+```
+
+(You might argue that the two assigments within the first @if@ should count as statements, and that perhaps the nested assignment should count as +2.)
+
+## Configuration
+
+`reek`'s `Too Many Statements` detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option | Value | Effect |
+| ---------------|-------------|---------|
+| `max_statements` | integer | The maximum number of statements allowed in a method before a warning is issued. Defaults to 5. |
+
+`Too Many Statements`'s default configuration is:
+
+```yaml
+---
+TooManyStatements:
+ enabled: true
+ exclude:
+ - initialize
+ max_statements: 5
+```
+
+By default, `initialize` is not checked for length; any class's constructor can be as long as necessary.
diff --git a/docs/Uncommunicative-Method-Name.md b/docs/Uncommunicative-Method-Name.md
new file mode 100644
index 000000000..3a299b5a7
--- /dev/null
+++ b/docs/Uncommunicative-Method-Name.md
@@ -0,0 +1,24 @@
+# Uncommunicative Method Name
+
+## Introduction
+
+An `Uncommunicative Method Name` is a method name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in reek
+
+`Uncommunicative Method Name` checks for:
+
+* 1-character names
+* any name ending with a number
+* camelCaseVariableNames
+
+## Configuration
+
+`reek`'s Uncommunicative Method Name detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option | Value | Effect |
+| ---------------|-------------|---------|
+| `reject` | array of regular expressions | The set of regular expressions that `reek` uses to check for bad names. Defaults to `[/^[a-z]$/, /[0-9]$/, /[A-Z]/]`. |
+| `accept` | array of strings or regular expressions | Name that will be accepted (not reported) even if they match one of the `reject` expressions. |
\ No newline at end of file
diff --git a/docs/Uncommunicative-Module-Name.md b/docs/Uncommunicative-Module-Name.md
new file mode 100644
index 000000000..0d7390135
--- /dev/null
+++ b/docs/Uncommunicative-Module-Name.md
@@ -0,0 +1,23 @@
+# Uncommunicative Module Name
+
+## Introduction
+
+An `Uncommunicative Module Name` is a module name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in reek
+
+`Uncommunicative Module Name` checks for:
+
+* 1-character names
+* any name ending with a number
+
+## Configuration
+
+`reek`'s `Uncommunicative Module Name` detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option | Value | Effect |
+| ---------------|-------------|---------|
+| `reject` | array of regular expressions | The set of regular expressions that `reek` uses to check for bad names. Defaults to `[/^.$/, /[0-9]$/]`. |
+| `accept` | array of strings or regular expressions | Name that will be accepted (not reported) even if they match one of the `reject` expressions. Defaults to `['Inline::C']`.|
\ No newline at end of file
diff --git a/docs/Uncommunicative-Name.md b/docs/Uncommunicative-Name.md
new file mode 100644
index 000000000..df0e7f234
--- /dev/null
+++ b/docs/Uncommunicative-Name.md
@@ -0,0 +1,16 @@
+# Uncommunicative Name
+
+## Introduction
+
+An `Uncommunicative Name` is a name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in Reek
+
+`reek` offers four related checks:
+
+* [Uncommunicative Method Name](Uncommunicative-Method-Name.md)
+* [Uncommunicative Module Name](Uncommunicative-Module-Name.md)
+* [Uncommunicative Parameter Name](Uncommunicative-Parameter-Name.md)
+* [Uncommunicative Variable Name](Uncommunicative-Variable-Name.md)
\ No newline at end of file
diff --git a/docs/Uncommunicative-Parameter-Name.md b/docs/Uncommunicative-Parameter-Name.md
new file mode 100644
index 000000000..ff1c2ca36
--- /dev/null
+++ b/docs/Uncommunicative-Parameter-Name.md
@@ -0,0 +1,24 @@
+# Uncommunicative Parameter Name
+
+## Introduction
+
+An `Uncommunicative Parameter Name` is a parameter name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in reek
+
+`Uncommunicative Parameter Name` checks for:
+
+* 1-character names
+* any name ending with a number
+* camelCaseVariableNames
+
+## Configuration
+
+`reek`'s Uncommunicative Parameter Name detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option | Value | Effect |
+| ---------------|-------------|---------|
+| `reject` | array of regular expressions | The set of regular expressions that `reek` uses to check for bad names. Defaults to `[/^.$/, /[0-9]$/, /[A-Z]/]@. |
+| `accept` | array of strings or regular expressions | Name that will be accepted (not reported) even if they match one of the `reject` expressions. |
\ No newline at end of file
diff --git a/docs/Uncommunicative-Variable-Name.md b/docs/Uncommunicative-Variable-Name.md
new file mode 100644
index 000000000..f1822c680
--- /dev/null
+++ b/docs/Uncommunicative-Variable-Name.md
@@ -0,0 +1,24 @@
+# Uncommunicative Variable Name
+
+## Introduction
+
+An `Uncommunicative Variable Name` is a variable name that doesn't communicate its intent well enough.
+
+Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.
+
+## Current Support in Reek
+
+`Uncommunicative Variable Name` checks for:
+
+* 1-character names
+* any name ending with a number
+* camelCaseVariableNames
+
+## Configuration
+
+`reek`'s `Uncommunicative Variable Name` detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option | Value | Effect |
+| ---------------|-------------|---------|
+| `reject` | array of regular expressions | The set of regular expressions that `reek` uses to check for bad names. Defaults to `[/^.$/, /[0-9]$/, /[A-Z]/]`. |
+| `accept` | array of strings or regular expressions | Name that will be accepted (not reported) even if they match one of the `reject` expressions. Defaults to @['_']@.|
\ No newline at end of file
diff --git a/docs/Unused-Parameters.md b/docs/Unused-Parameters.md
new file mode 100644
index 000000000..9f1b52f31
--- /dev/null
+++ b/docs/Unused-Parameters.md
@@ -0,0 +1,27 @@
+## Introduction
+
+`Unused Parameter` refers to methods with parameters that are unused in scope of the method.
+
+Having unused parameters in a method is code smell because leaving dead code in a method can never improve the method and it makes the code confusing to read.
+
+## Example
+
+Given:
+
+```Ruby
+class Klass
+ def unused_parameters(x,y,z)
+ puts x,y # but not z
+ end
+end
+```
+
+`reek` would emit the following warning:
+
+```
+[2]:Klass#unused_parameters has unused parameter 'z' (UnusedParameters)
+```
+
+## Configuration
+
+`Unused Parameter` offers the [Basic Smell Options](Basic-Smell-Options.md).
\ No newline at end of file
diff --git a/docs/Utility-Function.md b/docs/Utility-Function.md
new file mode 100644
index 000000000..ccf7a0a98
--- /dev/null
+++ b/docs/Utility-Function.md
@@ -0,0 +1,46 @@
+# Utility Function
+
+## Introduction
+
+A Utility Function is any instance method that has no dependency on the state of the instance.
+
+A Utility Function reduces the code’s ability to communicate intent: code that “belongs” on one class but which is located in another can be hard to find, and may upset the “System of Names” in the host class. A Utility Function also affects the design’s flexibility: A code fragment that is in the wrong class creates couplings that may not be natural within the application’s domain, and creates a loss of cohesion in the unwilling host class.
+
+A Utility Function often arises because it must manipulate other objects (usually its arguments) to get them into a useful form, and one force preventing them (the arguments) doing this themselves is that the common knowledge lives outside the arguments, or the arguments are of too basic a type to justify extending that type. Therefore there must be something which 'knows' about the contents or purposes of the arguments. That thing would have to be more than just a basic type, because the basic types are either containers which don't know about their contents, or they are single objects which can't capture their relationship with their fellows of the same type. So, this thing with the extra knowledge should be reified into a class, and the utility method will most likely belong there.
+
+## Example
+
+Given
+
+```Ruby
+class UtilityFunction
+ def showcase(argument)
+ argument.to_s + argument.to_i
+ end
+end
+```
+
+`reek` would report:
+
+```
+test.rb -- 2 warnings:
+ [2]:UtilityFunction#showcase doesn't depend on instance state (UtilityFunction)
+```
+
+## Current Support in reek
+
+`Utility Function` will warn about any method that:
+
+* is non-empty
+* does not override an inherited method
+* calls at least one method on another object
+* doesn't use any of self's instance variables
+* doesn't use any of self's methods
+
+## Configuration
+
+`reek`'s `Utility Function` detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option | Value | Effect |
+| ---------------|-------------|---------|
+| `max_helper_calls` | integer | The maximum number of method calls to other objects allowed within a method. Defaults to 2. |
diff --git a/docs/Working-with-Rails.md b/docs/Working-with-Rails.md
new file mode 100644
index 000000000..d72bd9b43
--- /dev/null
+++ b/docs/Working-with-Rails.md
@@ -0,0 +1,7 @@
+# Working with Rails
+
+With current versions of `reek` it's best to examine only your `app/models` folder, because `reek` raises false positives against views and controllers.
+
+For example, `params` is a kind of DTO (data transfer object) close to the system boundary, and so its characteristics should be different than regular code. But Reek doesn't know that (yet); `reek` thinks that all those `params[:something]` calls are a problem, and reports them as smells.
+
+We plan to improve Reek in the near future so that it plays better with Rails. For now though, your best bet is to restrict it to looking at `app/models` (and maybe `app/helpers` and `lib`).
diff --git a/docs/YAML-Reports.md b/docs/YAML-Reports.md
new file mode 100644
index 000000000..a2fdef1da
--- /dev/null
+++ b/docs/YAML-Reports.md
@@ -0,0 +1,111 @@
+# YAML Reports
+
+## Introduction
+
+`Reek`'s `--yaml` option writes on $stdout a YAML dump of the smells found. Each reported smell has a number of standard fields and a number of fields that are specific to the smell's type. The common fields are as follows:
+
+| Field | Type | Value |
+| ---------------|-------------|---------|
+| source | string | The name of the source file containing the smell, or `$stdin` |
+| lines | array | The source file line number(s) that contribute to this smell |
+| context | string | The name of the class, module or method containing the smell |
+| class | string | The class to which this smell belongs |
+| subclass | string | This smell's subclass within the above class |
+| message | string | The message that would have been printed in a standard Reek report |
+| is_active | boolean | `false` if the smell is masked by a config file; `true` otherwise |
+
+All of these fields are grouped into hashes `location`, `smell` and `status` (see the examples below).
+
+## Examples
+
+Duplication:
+
+
+- !ruby/object:Reek::SmellWarning
+ location:
+ source: spec/samples/masked/dirty.rb
+ lines:
+ - 5
+ - 7
+ context: Dirty#a
+ smell:
+ class: Duplication
+ subclass: DuplicateMethodCall
+ occurrences: 2
+ call: puts(@s.title)
+ message: calls puts(@s.title) twice
+ status:
+ is_active: true
+
+
+[Nested Iterators](Nested-Iterators.md):
+
+
+- !ruby/object:Reek::SmellWarning
+ location:
+ source: spec/samples/masked/dirty.rb
+ lines:
+ - 5
+ context: Dirty#a
+ smell:
+ class: NestedIterators
+ subclass: ""
+ depth: 2
+ message: contains iterators nested 2 deep
+ status:
+ is_active: true
+
+
+[Uncommunicative Method Name](Uncommunicative-Method-Name.md):
+
+
+- !ruby/object:Reek::SmellWarning
+ location:
+ source: spec/samples/masked/dirty.rb
+ lines:
+ - 3
+ context: Dirty#a
+ smell:
+ class: UncommunicativeName
+ subclass: UncommunicativeMethodName
+ method_name: a
+ message: has the name 'a'
+ status:
+ is_active: false
+
+
+[Uncommunicative Variable Name](Uncommunicative-Variable-Name.md):
+
+
+- !ruby/object:Reek::SmellWarning
+ location:
+ source: spec/samples/masked/dirty.rb
+ lines:
+ - 5
+ context: Dirty#a
+ smell:
+ class: UncommunicativeName
+ subclass: UncommunicativeVariableName
+ variable_name: x
+ message: has the variable name 'x'
+ status:
+ is_active: true
+
+
+[Control Couple](Control-Couple.md):
+
+
+- !ruby/object:Reek::SmellWarning
+ location:
+ source: $stdin
+ lines:
+ - 2
+ context: Turn#fred
+ smell:
+ class: ControlCouple
+ subclass: BooleanParameter
+ parameter: arg
+ message: has boolean parameter 'arg'
+ status:
+ is_active: true
+