README.md in code-box-0.3.1 vs README.md in code-box-0.4.0

@@ -1,12 +1,18 @@
 # CodeBox::CodeAttribute
 
 Lets you define attributes as codes, instead keys (ids). For simple option storage saving a string code is often more simple an conveniant the storing an artificial id-key referencing a special code object.
-CodeBox lets you access define codes as strings and access the associated code objects in various ways.
 
+CodeBox:
 
+* lets you define code attributes
+* provides translation of this codes __or__
+* provides access to associated code objects (see below) in various ways
+* __and__ furthermore enables an easy way to define code objects
 
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
     gem 'code-box'
@@ -65,11 +71,11 @@
       attr_accessor :nationality_code
 
       code_attribute :nationality, :lookup_type => :lookup
     end
 
-    # Note: Below class is a plain sample implementation. Code objects can be built easier with
+    # Note: Below class is a plain sample implementation. Code objects can be built easier with
     #       'ActsAsCode' include (see below)
     class Code::Nationality
       attr_accessor :code, :name
 
       def self.for_code(code)
@@ -118,48 +124,51 @@
 
 As describe above code_attributes can reference code objects if the `code_attribute` is of type `:associated` or `:lookup`.
 
 Making an code object `acts_as_code` provides the following features:
 
-  * `#translated_code(locale=I18n.locale, *other_locale_options)
-    Translates the code stored in `code`
+  * `#translated_code(locale=I18n.locale, *other_locale_options)`
+    <br/>Translates the code stored in `code`
 
-  * `&#35;translated_code(locale=I18n.locale, *other_locale_options)`
-    Translates the code stored in `code`
+  * `#translated_code(locale=I18n.locale, *other_locale_options)`
+    <br/>Translates the code stored in `code`
 
   * `.translate_code(code, *options)`
-    Translates a single code if `code` is a code, an array of codes of `code` is an array.
+    <br/>Translates a single code if `code` is a code, an array of codes of `code` is an array.
     If code is an array the option :build => :zip can be used to build a select option capable array (e.g `[['Switzerland', 'SUI'],['Germany', 'GER'],['Denmark', 'DEN']]`)
 
-  * `.for_code(code)
-    Answers the code object for the given code (fetched from cache)
+  * `.for_code(code)`:
+    <br/>Answers the code object for the given code (fetched from cache)
 
   * `.clear_code_cache`
-    Clears the cache so its build up on need from all codes from scratch
+    <br/>Clears the cache so its build up on need from all codes from scratch
 
 
   __Note:__ The code name can be configures using the `:code_attribute` option.
-  `:code_attribute => :iso_code` leads to methods like #translate_iso_code etc.
+  `:code_attribute => :iso_code` leads to methods like `#translate_iso_code` etc.
 
 
 #### Plain old ruby object codes (:poro)
 
-Assuming we have a simple ruby class with default code attribute 'code' we can defined such a class like
+Assuming we have a simple ruby class with default code attribute 'code' we can defined such a class like:
 
     class Codes::MySpecificCode
-      include CodeBox::ActsAsCode
+      include CodeBox::ActsAsCode[]
+      # Above is actually a shortcut for:
+      #   include CodeBox::ActsAsCode
+      #   acts_as_code
 
-      # Above include cretes the following:
+      # Above include creates the following:
       #
       # attr_accessor :code
       #
-      # def initialize(code)
-      #  @code = code
+      # def initialize(code)
+      #  @code = code
       # end
-      #
+      #
       # def self.all
-      #   raise "Sublass responsibility. You should implement '.all' returning all codes"
+      #   raise "Sublass responsibility. You should implement '.all' returning all codes"
       # end
 
       # @return [Array] List if all code objects (instances of this)
       def self.all
         # you need to implement this
@@ -178,11 +187,14 @@
 
 Assuming we have an ActiveRecod code class with `code_attribute :code` we can defined such a class like
 
     class Codes::MySpecificCode < ActiveRecord::Base
       include CodeBox::ActsAsCode[:type => :active_record]
+      # Above is actually a shortcut for:
+      #   include CodeBox::ActsAsCode
+      #   acts_as_code(:type => :active_record)
 
-      # Above include cretes the following:
+      # Above include creates the following:
       #
       # validates_presence_of   :code
       # validates_uniqueness_of :code
       #
       # default_scope order('code')