working on docs..

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

README.md

@@ -444,18 +444,68 @@ _action_ is build-in.
 ## Features
 
 Features is a module that helps build _features_ out of sets of actions
-and manage sets of features according to external criteria and 
+apply them to objects and manage sets of features via external criteria
-feature-feature dependencies.
+and feature-to-feature dependencies.
 
 
 ### The main entities:
 
-**Feature**
+**FeatureSet (Features)**
+
+```javascript
+var feature_set = new FeatureSet()
+```
 
 XXX
 
 
-**FeatureSet (Features)**
+**Feature**
+```javascript
+feature_set.Feature({
+  tag: 'minimal_feature_example',
+})
+
+feature_set.Feature({
+  // documentation (optional)...
+  title: 'Example Feature',
+  doc: 'A feature to demo the base API...',
+
+  // feature unique identifier (required)...
+  tag: 'feature_example',
+
+  // applicability test (optional)
+  isApplicable: function(){ /* ... */ },
+
+  // feature load priority (optional)
+  priority: 'medium',
+
+  // list of feature tags to load if available (optional)
+  suggested: [],
+
+  // list of feature tags required to load before this feature (optional)
+  depends: [],
+
+  // Exclusive tag (optional)
+  exclusive: 'Example feature',
+
+  // feature configuration (optional)
+  config: {
+    option: 'value',
+    // ...
+  },
+
+  // actions (optional)
+  actions: Actions({
+    // ...
+  })
+
+  // action handlers (optional)
+  handlers: [
+    ['action.pre', function(){ /* ... */ }],
+    // ...
+  ] 
+})
+```
 
 XXX