Add usage examples to API/SPI classes

We should start adding Usage Examples to API and SPIs with a Description of the Concept this represent.

The future usage is to build up a reference dictionary, see current version:
https://github.com/arquillian/arquillian-core/blob/master/container/test-api/src/main/java/org/jboss/arquillian/container/test/api/Deployment.java

Example:
http://staging-arquilliandev.rhcloud.com/code/reference/#org.jboss.arquillian.container.test.api.Deployment

Arquillian.org issue: https://github.com/arquillian/arquillian.github.com/issues/87