README.md in konstructor-0.2.0 vs README.md in konstructor-0.3.0

@@ -9,11 +9,11 @@
 # Konstructor
 
 Konstructor is a small gem that gives you multiple
 constructors in Ruby.
 
-Use `konstructor` keyword to define constructors additional to the defaul one:
+Use `konstructor` keyword to declare constructors additional to the defaul one:
 ```ruby
 class SomeClass
   konstructor
   def create(val)
     @val = val
@@ -42,44 +42,47 @@
 
 You can also install it without Bundler:
 
     $ gem install konstructor
 
-If you wish to manually include Konstructor in your classes only when
-you need it, see [Manual include](https://github.com/snovity/konstructor/wiki/Manual-include) page.
+If you are a gem author or just wish to manually include `konstructor` 
+keyword in your classes only when you need it, see 
+[Manual include](https://github.com/snovity/konstructor/wiki/Manual-include) page.
    
 ## Usage
 
-In simplest form `konstructor` creates a constructor from the next method.
+In its simplest form `konstructor` declaration creates a 
+constructor from the next method.
 
  ```ruby
- konstructor
- def create
- end
+  konstructor
+  def create
+  end
  
- konstructor
- def recreate
- end
+  konstructor
+  def recreate
+  end
  ```
  
 When method names are given, it creates constructors from 
 those methods without affecting the next method.
  
  ```ruby
- konstructor :create, :recreate
+  konstructor :create, :recreate
  
- def not_constructor
- end
+  def not_constructor
+  end
  
- def create
- end
+  def create
+  end
  
- def recreate
- end
+  def recreate
+  end
  ```
  
- Call with method names can be placed anywhere in class definition.
+ Declaration with method names can be placed anywhere in 
+ class definition.
  
  ```ruby
   def create
   end
   konstructor :create
@@ -87,31 +90,41 @@
   konstructor
   def recreate
   end
  ```
  
- In all above cases the class will have the default constructor 
+ In all above cases `SomeClass` will have the default constructor 
  and two additional ones.
  
  ```ruby
  obj0 = SomeClass.new
  obj1 = SomeClass.create
  obj2 = SomeClass.recreate
  ```
  
-### Same as default constructor
+ If you decide to remove the default Ruby constructor for some reason,
+ you can effectively do it by marking it as private using Ruby 
+ method `private_class_method`:
  
-Additional constructors work exactly the same way as 
-built-in Ruby constructor. 
+ ```ruby
+ class SomeClass
+   private_class_method :new
+ end   
+ ```
+  
+#### Same as default constructor
+ 
+Additional constructors work exactly the same way as the default one.
 
 You can pass blocks to them. 
 
 ```ruby
-konstructor
-def create(val)
-  @val = yield val
-end
+  konstructor
+  def create(val)
+    @val = yield val
+  end
+  #...
 
 obj = SomeClass.create(3) { |v| v*3 }
 obj.val # 9
 ```
 
@@ -133,102 +146,58 @@
 end
 
 obj = SomeSubclass.create(2, 3)
 obj.val # 6
 ``` 
-Once method is a marked as konstructor in hierarchy, 
-it is always a konstructor.
-                                   
-Methods inherited from superclasses can't become konstructors in 
-subclasses. To achieve the effect, define a new method, 
-mark it as konstructor and call the inherited one. 
+Once method is declared as `konstructor` in hierarchy, 
+it is always a constructor.
 
-### Reserved names
+There are certain limitations to what can be declared as `konstructor`, 
+see 
+[Limitations page](https://github.com/snovity/konstructor/wiki/Limitations)
+for details.
 
-Using reserved method names `new` and `initialize` for additional 
-constructor declaration will raise an error:
-```ruby
-konstructor
-def initialize # raises Konstructor::ReservedNameError
-end
-```
-or
-```ruby
-konstructor
-def new # raises Konstructor::ReservedNameError
-end
-```
+#### Using with other gems
 
-### Defining konstructors in Modules
-
-Modules can't have konstructors. Use `ActiveSupport::Concern` and 
-define konstructor in `included` block.
-
-### Using with other gems
-
 Konstructor doesn't affect other gems, including those
-that depend on metaprogramming, such as [rake](https://github.com/ruby/rake), [thor](https://github.com/erikhuda/thor), [contracts](https://github.com/egonSchiele/contracts.ruby), etc.
+that depend on metaprogramming, such as 
+[rake](https://github.com/ruby/rake),
+[thor](https://github.com/erikhuda/thor), 
+[contracts](https://github.com/egonSchiele/contracts.ruby), etc.
 
-For instnace, this is how Konstructor works with contracts gem:
+For instnace, this is how Konstructor works with contracts:
 ```ruby
-  class SomeClass
-    konstructor
-    Contract Num => SomeClass
-    def create(some_number)
-      @number = some_number
-    end
-  end    
+class SomeClass
+  konstructor
+  Contract Num => SomeClass
+  def create(some_number)
+    @number = some_number
+  end
+end    
 ```
   
 If you stumble upon a metaprogramming gem that 
-conflicts with Konstructor, please [open an issue](https://github.com/snovity/konstructor/issues/new).
+conflicts with Konstructor, please 
+[open an issue](https://github.com/snovity/konstructor/issues/new).
+  
+## Details
 
-### Removing default constructor
+Ruby constructor is a pair consisting of public factory method defined
+on a class and a private instance method. Therefore, to achieve 
+its goal `konstructor` marks instance method as private and defines a 
+corresponding public class method with the same name.
 
-You can effectively remove default Ruby constructor
-by marking it as private:
-```ruby
-class SomeClass
-  private_class_method :new
-end   
-```
+#### Performance
  
-## Performance
- 
 Konstructor does all its work when class is being defined. Once class
 has been defined, it's just standard Ruby instance creation.
 Therefore, there is no runtime performance penalty. 
 
 Konstructor doesn't depend on other gems.
   
-## Thread safety
+#### Thread safety
   
 Konstructor is thread safe.
-  
-## Details
-
-Ruby constructor is a pair consisting of public factory method defined
-on a class and a private instance method. Therefore, to achieve 
-its goal `konstructor` marks instance method as private and defines a 
-corresponding public class method with the same name.
-
-You can check if certain instance method name has been declared as 
-constructor or is a default constructor by running.
-```ruby
-Konstructor.is?(SomeClass, :initialize) # true
-Konstructor.is?(SomeClass, :create) # true
-Konstructor.is?(SomeClass, :recreate) # true
-Konstructor.is?(SomeClass, :something_else) # false
-``` 
- 
-It will return true even if no such constructor has 
-been defined yet. Like:
-```ruby
-class SomeClass
-  konstructor :create
-end
-```
-Konstructor body may be supplied in subclasses.
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at 
 https://github.com/snovity/konstructor. This project is intended to be