first off read me

README.md

@@ -1,18 +1,114 @@
-Validator
+garðr-validator
 =========
+
+Collect data from a display-ads lifecyle and validate the data. This project tries to give a nice framework for doing this.
+
 [![Build Status](https://travis-ci.org/gardr/validator.png)](https://travis-ci.org/gardr/validator)
 [![Coverage Status](https://coveralls.io/repos/gardr/validator/badge.png)](https://coveralls.io/r/gardr/validator)
 [![NPM version](https://badge.fury.io/js/gardr-validator.png)](http://badge.fury.io/js/gardr-validator)
 [![Dependency Status](https://david-dm.org/gardr/validator.png)](https://david-dm.org/gardr/validator)
 [![devDependency Status](https://david-dm.org/gardr/validator/dev-status.png)](https://david-dm.org/gardr/validator#info=devDependencies)
 
-# Installation
+#### Installation
 
 	$ npm install
 
-# Contributing
+### Examples
+
+See the web-gui for this project: https://github.com/gardr/validator-web/blob/master/lib/routes/validate.js#L284
+
+
+#### Writing intrumentation and validators
+
+##### Intrument / Hook example filename: 'someData.js':
+    module.exports = {
+        'onBeforeExit': function (api, config) {
+            api.switchToIframe();
+            if (config.someConfigBoolean){
+                api.set('collectedData', api.evaluate(function(config){
+                    return window.someData;
+                }, config));
+            }
+        }
+    };
+
+##### Preprocessor example filename 'fixSomethingAsync.js'
+    module.exports = {
+        'dependencies': ['someData'],
+        'preprocess': function(harvested, output, next, globalOptions){
+            output('someKey', {data: harvested.someData||{}});
+            setTimeout(next, 1);
+        }
+    };
+
+##### Validator example filename 'someData.js'
+    module.exports = {
+        'preprocessors': [
+            'fixSomethingAsync'
+        ],
+        'dependencies': [
+            'someData'
+        ],
+        'validate': function(harvested, report, next, globalOptions){
+            if (this.someConfigBoolean){
+                if (harvested.someData){
+                    report.error('Some message');
+                }
+            }
+        }
+    };
+
+##### Adding instrumentation/hooks etc to a run
+
+    var run = require('gardr-validator');
+    var options = {
+        'include': [
+            {
+                name: 'someData',
+                path: '/resolved/path/to/someData.js'
+            }
+        ],
+        'config':{
+            'someData': {
+                'someConfigBoolean': true
+            }
+        }
+    };
+    run(options, function(phantomError, harvest, report){
+        if (phantomError){
+            // do something
+            return;
+        }
+        assert(harvest.someData);
+        assert(harvest.someKey);
+        assert(report.errors.length === 1);
+    })
+
+#### Options to runner
+    {
+        instrument: [
+            'actions', // defaults to files in /lib/rule/instrument/actions.js
+            {name: 'css'},
+            {name: 'custom', path: '/absolute/path/to/file'},
+            {name: 'custom2', code: 'var someCode = "";'}
+        ],
+        preprocess: [
+            //..
+        ],
+        validate: [
+            //..
+        ]
+        //rest of runner default options, see /config folder.
+    }
+
+
+#### Contributing
+YES, pull requests with tests. Be sure to create a issue and let us know you are working on it - maybe we can help out with insights etc.
 
 ## Running tests
 
 	$ npm test
 
+##### Alternatives
+
+(please let us know of alternatives to this project)