Added 'Usage' section to newly structure docs

- Added > icon in front of each parameter
- Added acceptable types to parameters

docs/source/api/commands/click.md

@@ -17,21 +17,42 @@ Click a DOM element.  The DOM element must be in a "clickable" state prior to th
 .click(x, y, options)
 ```
 
+## Usage
+
+`.click()` requires being chained off another cy command that *yields* a DOM element.
+
+**{% fa fa-check-circle green %} Valid Usage**
+
+```javascript
+cy.get('button').click()               // Clicks on button
+cy.focused().click()                   // Clicks on el with focus
+cy.contains('Welcome').first().click() // Clicks on first el containing 'Welcome'
+```
+
+**{% fa fa-exclamation-triangle red %} Invalid Usage**
+
+```javascript
+cy.click('button')          // Errors, cannot be chained off 'cy'
+cy.window().click()         // Errors, 'window' does not yield DOM element
+```
+
 ## Arguments
 
-**position**
+**{% fa fa-angle-right %} position** ***(String)***
 
 Clicks the element at the specified position. The `center` position is the default position. Valid positions are `topLeft`, `top`, `topRight`, `left`, `center`, `right`, `bottomLeft`, `bottom`, and `bottomRight`.
 
 ![cypress-command-positions-diagram](https://cloud.githubusercontent.com/assets/1271364/25048528/fe0c6378-210a-11e7-96bc-3773f774085b.jpg)
 
-**x**, **y**
+**{% fa fa-angle-right %} x** ***(Number)***
 
-You can pass a relative `x` and `y` coordinate which will calculate distance in pixels from the top left corner of the element and issue the click at the calculated coordinate.
+The distance in pixels from element's left to issue the click.
 
-`x` and `y` must both be `Numbers`. Currently you cannot use `%` based arguments. [Open an issue](https://github.com/cypress-io/cypress/issues/new) if you'd like this functionality.
+**{% fa fa-angle-right %} y** ***(Number)***
 
-**options** *(optional)*
+The distance in pixels from element's top to issue the click.
+
+**{% fa fa-angle-right %} options** ***(Object)***
 
 Pass in an options object to change the default behavior of `.click`.
 

docs/source/api/commands/contains.md

@@ -14,21 +14,35 @@ cy.contains(selector, content)
 cy.contains(selector, content, options)
 ```
 
-## Parameters
+## Usage
 
-**content**
+`.contains()` can be chained off of `cy` to find content within the entire document or chained off another cy command that *yields* a DOM element - limiting it's search of content to within yielded element.
 
-Get the deepest DOM element containing the content. Content can be a:
+**{% fa fa-check-circle green %} Valid Usage**
 
-- *string*
-- *number*
-- *RegExp*
+```javascript
+cy.get('.nav').contains('About')  // Yields el in .nav containing 'About'
+cy.contains('Hello').first()      // Yields first el in document containing 'Hello'
+```
 
-**selector** *(optional)*
+**{% fa fa-exclamation-triangle red %} Invalid Usage**
+
+```javascript
+cy.title().contains('My App')        // Errors, 'title' does not yield DOM element
+cy.getCookies().contains('_key')     // Errors, 'getCookies' does not yield DOM element
+```
+
+## Arguments
+
+**{% fa fa-angle-right %} content** ***(String, Number, RegExp)***
+
+Get the deepest DOM element containing the content.
+
+**{% fa fa-angle-right %} selector** ***(String selector)***
 
 Specify a selector to filter DOM elements containing the text. Cypress will *ignore* it's [default preference order](#notes) for the specified selector. Using a selector allows you to return more *shallow* elements in the tree which contain the specific text.
 
-**options** *(optional)*
+**{% fa fa-angle-right %} options** ***(Object)***
 
 Pass in an options object to change the default behavior of `cy.contains`.
 

docs/source/api/commands/first.md

@@ -13,9 +13,27 @@ Get the first DOM element within a set of DOM elements.
 .first(options)
 ```
 
+## Usage
+
+`.first()` requires being chained off another cy command that *yields* a DOM element.
+
+**{% fa fa-check-circle green %} Valid Usage**
+
+```javascript
+cy.get('nav a').first()       // Yield first link in nav
+cy.contains('Hello').first()  // Yield first el containing Hello
+```
+
+**{% fa fa-exclamation-triangle red %} Invalid Usage**
+
+```javascript
+cy.first()                  // Errors, cannot be chained off 'cy'
+cy.getCookies().first()     // Errors, 'getCookies' does not yield DOM element
+```
+
 ## Arguments
 
-**options**
+**{% fa fa-angle-right %} options**  ***(Object)***
 
 Pass in an options object to change the default behavior of `cy.first`.
 

docs/source/api/commands/route.md

@@ -21,30 +21,38 @@ cy.route(function() {})
 cy.route(options)
 ```
 
+
+## Usage
+
+`.route()` cannot be chained off any other cy commands, so should be chained off of `cy` for clarity.
+
+**{% fa fa-check-circle green %} Valid Usage**
+
+```javascript
+cy.route('/users/**')    
+```
+
 ## Arguments
 
-**url**
+**{% fa fa-angle-right %} url** ***(String, Glob, RegExp)***
 
-Set a route matching the specific `url` which is not stubbed but can be waited on later. `url` can be a:
+Set a route matching the specific `url` which is not stubbed but can be waited on later.
 
-- *string*
-- *RegExp*
-
-**response** *(optional)*
+**{% fa fa-angle-right %} response** ***(String, Object)***
 
 Supply a response body to *stub* in the matching route.
 
-**method** *(optional)*
+**{% fa fa-angle-right %} method** ***(String)***
 
 Match the route to a specific method (`GET`, `POST`, `PUT`...). If no method is defined, Cypress will match `GET` requests by default.
 
-**function**
+**{% fa fa-angle-right %} function** ***(Function)***
 
 Set a route by returning an object literal from a callback function.
 
 Functions which return a promise will automatically be awaited.
 
-**options**
+**{% fa fa-angle-right %} options** ***(Object)***
 
 Pass in an options object to change the default behavior of `cy.route`. By default `cy.route` inherits its options from [`cy.server`](https://on.cypress.io/api/server).