Revamp our doc structure.

README.md

@@ -228,7 +228,10 @@ Or just run the whole test suite:
 bundle exec rake
 ```
 
-From then on please check out [the contributing guide](CONTRIBUTING.md).
+From then on you should check out:
+* [How reek works internally](docs/How-reek-works-internally.md)
+* [the contributing guide](CONTRIBUTING.md)
+
 
 If you don't feel like getting your hands dirty with code there are still other ways you can help us:
 
@@ -241,10 +244,18 @@ If you don't feel like getting your hands dirty with code there are still other
 
 * plain text (default)
 * HTML (`--format html`)
-* YAML (`--format yaml`)
+* YAML (`--format yaml`, see also [YAML Reports](docs/YAML-Reports.md))
 * JSON (`--format json`)
 * XML  (`--format xml`)
 
+## 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 `lib`.
+
 ## Additional resources
 
 ### Tools
@@ -257,6 +268,11 @@ If you don't feel like getting your hands dirty with code there are still other
 * [overcommit, a Git commit hook manager with support for
   `reek`](https://github.com/brigade/overcommit)
 
+### Miscellaneous
+
+* [Reek Driven Development](docs/Reek-Driven-Development.md)
+* [Versioning policy](docs/Versioning-Policy.md)
+
 ### More information
 
 * [Stack Overflow](https://stackoverflow.com/questions/tagged/reek)

docs/Versioning-Policy.md

@@ -0,0 +1,7 @@
+# Versioning Policy
+
+* CLI interface: Adding options is a non-breaking change, and would warrant an update of the minor version. Removing options is a breaking change and requires a major version update (we did this going to reek 2). Adding a report format probably also warrents a minor version upgrade.
+* API: We haven't really defined a 'public' API for using Reek programmatically, and we've only just started testing it. So, this is basically a blank slate at the moment. We will work on this as a part of the reek 3 release.
+* List of detected smells: Adding a smell warrants a minor release, removing a smell is a breaking change. This makes sense if you consider that the CLI allows running a single smell detector.
+* Consistency of detected smells: This is very hard to guarantee. If we fix a bug in one of the detectors, some fragrant code may become smelly, or vice versa. Right now we don't bother with this.
+* Smell configuration: The detectors are quite tolerant regarding configuration options that they don't recognize, so we regard any change here as only requiring a minor release.

lib/reek/cli/options.rb

@@ -9,6 +9,7 @@ module CLI
     #
     # Parses the command line
     #
+    # See docs/Command-Line-Options for details.
     class Options
       def initialize(argv = [])
         @argv    = argv

lib/reek/smells/attribute.rb

@@ -13,6 +13,7 @@ module Smells
     # that are private.
     #
     # TODO: Catch attributes declared "by hand"
+    # See docs/Attribute for details.
     #
     class Attribute < SmellDetector
       ATTR_DEFN_METHODS = [:attr, :attr_reader, :attr_writer, :attr_accessor]

lib/reek/smells/boolean_parameter.rb

@@ -10,6 +10,7 @@ module Smells
     # Currently Reek can only detect a Boolean parameter when it has a
     # default initializer.
     #
+    # See docs/Boolean-Parameter for details.
     class BooleanParameter < SmellDetector
       def self.smell_category
         'ControlCouple'

lib/reek/smells/class_variable.rb

@@ -11,6 +11,7 @@ module Smells
     # In particular, class variables can make it hard to set up tests (because
     # the context of the test includes all global state).
     #
+    # See docs/Class-Variable for details.
     class ClassVariable < SmellDetector
       def self.contexts # :nodoc:
         [:class, :module]

lib/reek/smells/control_parameter.rb

@@ -39,6 +39,7 @@ module Smells
     # that remains next to where the caller invokes it in
     # the source code.
     #
+    # See docs/Control-Parameter for details.
     class ControlParameter < SmellDetector
       def self.smell_category
         'ControlCouple'

lib/reek/smells/data_clump.rb

@@ -14,6 +14,7 @@ module Smells
     # Currently Reek looks for a group of two or more parameters with
     # the same names that are expected by three or more methods of a class.
     #
+    # See docs/Data-Clump for details.
     class DataClump < SmellDetector
       #
       # The name of the config field that sets the maximum allowed

lib/reek/smells/duplicate_method_call.rb

@@ -15,6 +15,7 @@ module Smells
     #     @other.thing + @other.thing
     #   end
     #
+    # See docs/Duplicate-Method-Call for details.
     class DuplicateMethodCall < SmellDetector
       # The name of the config field that sets the maximum number of
       # identical calls to be permitted within any single method.

lib/reek/smells/feature_envy.rb

@@ -32,6 +32,7 @@ module Smells
     # If the method doesn't reference self at all, +UtilityFunction+ is
     # reported instead.
     #
+    # See docs/Feature-Envy for details.
     class FeatureEnvy < SmellDetector
       def self.smell_category
         'LowCohesion'

lib/reek/smells/irresponsible_module.rb

@@ -7,6 +7,7 @@ module Smells
     # It is considered good practice to annotate every class and module
     # with a brief comment outlining its responsibilities.
     #
+    # See docs/Irresponsible-Module for details.
     class IrresponsibleModule < SmellDetector
       def self.contexts # :nodoc:
         [:class]

lib/reek/smells/long_parameter_list.rb

@@ -11,6 +11,7 @@ module Smells
     # Currently +LongParameterList+ reports any method or block with too
     # many parameters.
     #
+    # See docs/Long-Parameter-List for details.
     class LongParameterList < SmellDetector
       # The name of the config field that sets the maximum number of
       # parameters permitted in any method or block.

lib/reek/smells/long_yield_list.rb

@@ -6,6 +6,7 @@ module Smells
     # A variant on LongParameterList that checks the number of items
     # passed to a block by a +yield+ call.
     #
+    # See docs/Long-Yield-List for details.
     class LongYieldList < SmellDetector
       # The name of the config field that sets the maximum number of
       # parameters permitted in any method or block.

lib/reek/smells/module_initialize.rb

@@ -7,6 +7,7 @@ module Smells
     # hard to tell initialization order and parameters so having 'initialize'
     # in a module is usually a bad idea
     #
+    # See docs/Module-Initialize for details.
     class ModuleInitialize < SmellDetector
       def self.contexts # :nodoc:
         [:module]

lib/reek/smells/nested_iterators.rb

@@ -7,6 +7,7 @@ module Smells
     #
     # +NestedIterators+ reports failing methods only once.
     #
+    # See docs/Nested-Iterators for details.
     class NestedIterators < SmellDetector
       # The name of the config field that sets the maximum depth
       # of nested iterators to be permitted within any single method.

lib/reek/smells/nil_check.rb

@@ -4,6 +4,8 @@ module Reek
   module Smells
     # Checking for nil is a special kind of type check, and therefore a case of
     # SimulatedPolymorphism.
+    #
+    # See docs/Nil-Check for details.
     class NilCheck < SmellDetector
       def self.smell_category
         'SimulatedPolymorphism'

lib/reek/smells/prima_donna_method.rb

@@ -21,6 +21,7 @@ module Smells
     #
     # Such a method is called PrimaDonnaMethod and is reported as a smell.
     #
+    # See docs/Prima-Donna-Method for details.
     class PrimaDonnaMethod < SmellDetector
       def self.contexts # :nodoc:
         [:class]

lib/reek/smells/repeated_conditional.rb

@@ -22,6 +22,7 @@ module Smells
     # +RepeatedConditional+ checks for multiple conditionals
     # testing the same value throughout a single class.
     #
+    # See docs/Repeated-Conditional for details.
     class RepeatedConditional < SmellDetector
       # The name of the config field that sets the maximum number of
       # identical conditionals permitted within any single class.

lib/reek/smells/smell_detector.rb

@@ -6,6 +6,11 @@ module Smells
     #
     # Shared responsibilities of all smell detectors.
     #
+    # See
+    #   - docs/Basic-Smell-Options
+    #   - docs/Code-Smells
+    #   - docs/Configuration-Files
+    # for details.
     class SmellDetector
       attr_reader :source
 

lib/reek/smells/too_many_instance_variables.rb

@@ -9,6 +9,7 @@ module Smells
     # +TooManyInstanceVariables' reports classes having more than a
     # configurable number of instance variables.
     #
+    # See docs/Too-Many-Instance-Variables for details.
     class TooManyInstanceVariables < SmellDetector
       # The name of the config field that sets the maximum number of instance
       # variables permitted in a class.

lib/reek/smells/too_many_methods.rb

@@ -11,6 +11,7 @@ module Smells
     # methods, and excludes methods inherited from superclasses or included
     # modules.
     #
+    # See docs/Too-Many-Methods for details.
     class TooManyMethods < SmellDetector
       # The name of the config field that sets the maximum number of methods
       # permitted in a class.

lib/reek/smells/too_many_statements.rb

@@ -7,6 +7,7 @@ module Smells
     #
     # +TooManyStatements+ reports any method with more than 5 statements.
     #
+    # See docs/Too-Many-Statements for details.
     class TooManyStatements < SmellDetector
       # The name of the config field that sets the maximum number of
       # statements permitted in any method.

lib/reek/smells/uncommunicative_method_name.rb

@@ -15,6 +15,7 @@ module Smells
     # * 1-character names
     # * names ending with a number
     #
+    # See docs/Uncommunicative-Method-Name for details.
     class UncommunicativeMethodName < SmellDetector
       # The name of the config field that lists the regexps of
       # smelly names to be reported.

lib/reek/smells/uncommunicative_module_name.rb

@@ -15,6 +15,7 @@ module Smells
     # * 1-character names
     # * names ending with a number
     #
+    # See docs/Uncommunicative-Module-Name for details.
     class UncommunicativeModuleName < SmellDetector
       # The name of the config field that lists the regexps of
       # smelly names to be reported.

lib/reek/smells/uncommunicative_parameter_name.rb

@@ -15,6 +15,7 @@ module Smells
     # * 1-character names
     # * names ending with a number
     #
+    # See docs/Uncommunicative-Parameter-Name for details.
     class UncommunicativeParameterName < SmellDetector
       # The name of the config field that lists the regexps of
       # smelly names to be reported.

lib/reek/smells/uncommunicative_variable_name.rb

@@ -15,6 +15,7 @@ module Smells
     # * 1-character names
     # * names ending with a number
     #
+    # See docs/Uncommunicative-Variable-Name for details.
     class UncommunicativeVariableName < SmellDetector
       # The name of the config field that lists the regexps of
       # smelly names to be reported.

lib/reek/smells/unused_parameters.rb

@@ -5,6 +5,7 @@ module Smells
     #
     # Methods should use their parameters.
     #
+    # See docs/Unused-Parameters for details.
     class UnusedParameters < SmellDetector
       def self.smell_category
         'UnusedCode'

lib/reek/smells/utility_function.rb

@@ -34,6 +34,7 @@ module Smells
     # If the method does refer to self, but refers to some other object more,
     # +FeatureEnvy+ is reported instead.
     #
+    # See docs/Utility-Function for details.
     class UtilityFunction < SmellDetector
       def self.smell_category
         'LowCohesion'