fixed some jsdoc and added some markdown

README.md

@@ -179,41 +179,51 @@ The app will now be able to react on requests (/birds) and (/birds/about)
 
 ## API
 
-| Class         | Method        |
+| Class         | Method        | Short description |
-| ------------- | --------------|
+| ------------- | --------------| ----------------- |
-|Frontexpress   ||
+|Frontexpress |||
-||[frontexpress()](https://github.com/camelaissani/frontexpress/blob/master/docs/frontexpress.md#frontexpress-1)|
+||[frontexpress()](https://github.com/camelaissani/frontexpress/blob/master/docs/frontexpress.md#frontexpress-1)|Creates an instance of application|
-||[frontexpress.Router()](https://github.com/camelaissani/frontexpress/blob/master/docs/frontexpress.md#frontexpressrouter)|
+||[frontexpress.Router()](https://github.com/camelaissani/frontexpress/blob/master/docs/frontexpress.md#frontexpressrouter)|Creates a Router object|
-||[frontexpress.Middleware()](https://github.com/camelaissani/frontexpress/blob/master/docs/frontexpress.md#frontexpressmiddleware)|
+||[frontexpress.Middleware()](https://github.com/camelaissani/frontexpress/blob/master/docs/frontexpress.md#frontexpressmiddleware)|Creates a Middleware object|
-|||
+||||
-| Application   ||
+|Application |||
-||[set(setting, value)](https://github.com/camelaissani/frontexpress/blob/master/docs/application.md#applicationsetsetting-val) |
+||[set(setting, value)](https://github.com/camelaissani/frontexpress/blob/master/docs/application.md#applicationsetsetting-val)|Assigns a setting|
-||[listen(callback)](https://github.com/camelaissani/frontexpress/blob/master/docs/application.md#applicationlistencallback) |
+||[listen(callback)](https://github.com/camelaissani/frontexpress/blob/master/docs/application.md#applicationlistencallback)|Starts the application|
-||[route(uri)](https://github.com/camelaissani/frontexpress/blob/master/docs/application.md#applicationrouteuri) |
+||[route(uri)](https://github.com/camelaissani/frontexpress/blob/master/docs/application.md#applicationrouteuri)|Gets a Router initialized with a root path|
-||[use(uri, middleware)](https://github.com/camelaissani/frontexpress/blob/master/docs/application.md#applicationuseuri-middleware) |
+||[use(uri, middleware)](https://github.com/camelaissani/frontexpress/blob/master/docs/application.md#applicationuseuri-middleware)|Sets a middleware|
-|| get(uri, middleware) |
+||||
-|| post(uri, middleware) |
+||get(uri, middleware)|Applies a middleware on given path for a GET request|
-|| put(uri, middleware) |
+||post(uri, middleware)|Applies a middleware on given path for a POST request|
-|| delete(uri, middleware) |
+||put(uri, middleware)|Applies a middleware on given path for a PUT request|
-|| httpGet(request, success, failure) |
+||delete(uri, middleware)|Applies a middleware on given path for a DELETE request|
-|| httpPost(request, success, failure) |
+||||
-|| httpPut(request, success, failure) |
+||httpGet(request, success, failure)|Invokes a GET ajax request|
-|| httpDelete(request, success, failure) |
+||httpPost(request, success, failure)|Invokes a POST ajax request|
-|||
+||httpPut(request, success, failure)|Invokes a PUT ajax request|
-| Router        ||
+||httpDelete(request, success, failure)|Invokes a DELETE ajax request|
-||[use(middleware)](https://github.com/camelaissani/frontexpress/blob/master/docs/router.md#routerusemiddleware) |
+||||
-||[all(middleware)](https://github.com/camelaissani/frontexpress/blob/master/docs/router.md#routerallmiddleware) |
+|Router |||
-|| get(uri, middleware) |
+||[use(middleware)](https://github.com/camelaissani/frontexpress/blob/master/docs/router.md#routerusemiddleware)|Sets a middleware|
-|| post(uri, middleware) |
+||[all(middleware)](https://github.com/camelaissani/frontexpress/blob/master/docs/router.md#routerallmiddleware)|Sets a middleware on all HTTP method requests|
-|| put(uri, middleware) |
+||||
-|| delete(uri, middleware) |
+||get(uri, middleware)|Applies a middleware on given path for a GET request|
-|||
+||post(uri, middleware)|Applies a middleware on given path for a POST request|
-| Middleware    ||
+||put(uri, middleware)|Applies a middleware on given path for a PUT request|
-||[entered(request)](https://github.com/camelaissani/frontexpress/blob/master/docs/middleware.md#middlewareenteredrequest) |
+||delete(uri, middleware)|Applies a middleware on given path for a DELETE request|
-||[exited(request)](https://github.com/camelaissani/frontexpress/blob/master/docs/middleware.md#middlewareexitedrequest) |
+||||
-||[updated(request, response)](https://github.com/camelaissani/frontexpress/blob/master/docs/middleware.md#middlewareupdatedrequest-response) |
+|Middleware |||
-||[failed(request, response)](https://github.com/camelaissani/frontexpress/blob/master/docs/middleware.md#middlewarefailedrequest-response) |
+||[entered(request)](https://github.com/camelaissani/frontexpress/blob/master/docs/middleware.md#middlewareenteredrequest)|Invoked by the app before an ajax request is sent|
-||[next()](https://github.com/camelaissani/frontexpress/blob/master/docs/middleware.md#middlewarenext) |
+||[exited(request)](https://github.com/camelaissani/frontexpress/blob/master/docs/middleware.md#middlewareexitedrequest)|Invoked by the app before a new ajax request is sent|
+||[updated(request, response)](https://github.com/camelaissani/frontexpress/blob/master/docs/middleware.md#middlewareupdatedrequest-response)|Invoked by the app after an ajax request has responded|
+||[failed(request, response)](https://github.com/camelaissani/frontexpress/blob/master/docs/middleware.md#middlewarefailedrequest-response)|Invoked by the app after an ajax request has failed|
+||[next()](https://github.com/camelaissani/frontexpress/blob/master/docs/middleware.md#middlewarenext)|Allows to break the middleware chain execution|
+||||
+|middleware function |||
+||||
+|request object |||
+||||
+|response object |||
+
 ## License
 
  [MIT](LICENSE)

docs/application.md

@@ -1,6 +1,7 @@
 # Application
 
-## Application.set(setting, val) 
+
+## Application.set(setting, val)
 
 Assign `setting` to `val`, or return `setting`'s value.
 
@@ -19,9 +20,9 @@ Assign `setting` to `val`, or return `setting`'s value.
 **Returns**: `app`, for chaining
 
 
-## Application.listen(callback) 
+## Application.listen(callback)
 
-Listen to DOM initialization and history state changes.
+Listen to the DOM initialization and the browser history state changes.
 
 The callback function is called once the DOM has
 the `document.readyState` equals to 'interactive'.
@@ -38,9 +39,9 @@ the `document.readyState` equals to 'interactive'.
   **callback**: `function`, DOM is ready callback
 
 
-## Application.route(uri) 
+## Application.route(uri)
 
-Returns a new `Router` instance for the _uri_.
+Create a new `Router` instance for the _uri_.
 See the Router api docs for details.
 
 ```js
@@ -55,7 +56,7 @@ See the Router api docs for details.
 **Returns**: `Router`, for chaining
 
 
-## Application.use(uri, middleware) 
+## Application.use(uri, middleware)
 
 Use the given middleware function or object, with optional _uri_.
 Default _uri_ is "/".
@@ -75,3 +76,59 @@ Default _uri_ is "/".
    **middleware**: `Middleware | function`, Middleware object or function
 
 **Returns**: `app`, for chaining
+
+
+## Application.get(uri, middleware), Application.post(uri, middleware)...
+
+Use the given middleware function or object, with optional _uri_ on
+HTTP methods: get, post, put, delete...
+Default _uri_ is "/".
+
+```js
+     // middleware function will be applied on path "/"
+     app.get((req, res, next) => {console.log('Hello')});
+
+     // middleware object will be applied on path "/" and
+     app.get(new Middleware());
+
+     // get a setting value
+     app.set('foo', 'bar');
+     app.get('foo');
+     // => "bar"
+```
+
+**Parameters**
+
+  **uri**: `String`, path (or setting only for get method)
+
+  **middleware**: `Middleware | function`, Middleware object or function
+
+**Returns**: `app`, for chaining
+
+
+## Application.httpGet(request, success, failure), Application.httpPost(request, success, failure)...
+
+Make an ajax request (get, post, put, delete...).
+
+```js
+   // HTTP GET method
+   httpGet('/route1');
+
+   // HTTP GET method
+   httpGet({uri: '/route1', data: {'p1': 'val1'});
+   // uri invoked => /route1?p1=val1
+
+   // HTTP GET method with browser history management
+   httpGet({uri: '/api/users', history: {state: {foo: "bar"}, title: 'users page', uri: '/view/users'});
+```
+
+Samples above can be applied on other HTTP methods.
+
+**Parameters**
+
+      **request**: `String | Object` uri or object containing uri, http headers, data, history
+
+      **success**: `Function` success callback
+
+      **failure**: `Function` failure callback
+

docs/middleware.md

@@ -1,6 +1,6 @@
 # Middleware
 
-## Middleware.entered(request) 
+## Middleware.entered(request)
 
 Invoked by the app before ajax request are sent or
 during the DOM loading (document.readyState === 'loading').
@@ -10,10 +10,10 @@ Override this method to add your custom behaviour
 
 **Parameters**
 
-**request**: `Object`
+  **request**: `Object`
 
 
-## Middleware.exited(request) 
+## Middleware.exited(request)
 
 Invoked by the app before a new ajax request is sent or before the DOM unloading.
 See Application#_callMiddlewareExited documentation for details.
@@ -22,10 +22,10 @@ Override this method to add your custom behaviour
 
 **Parameters**
 
-**request**: `Object`
+  **request**: `Object`
 
 
-## Middleware.updated(request, response) 
+## Middleware.updated(request, response)
 
 Invoked on ajax request responding or on DOM ready
 (document.readyState === 'interactive').
@@ -35,12 +35,12 @@ Override this method to add your custom behaviour
 
 **Parameters**
 
-**request**: `Object`
+  **request**: `Object`
 
-**response**: `Object`
+  **response**: `Object`
 
 
-## Middleware.failed(request, response) 
+## Middleware.failed(request, response)
 
 Invoked when ajax request fails.
 
@@ -48,12 +48,12 @@ Override this method to add your custom behaviour
 
 **Parameters**
 
-**request**: `Object`
+  **request**: `Object`
 
-**response**: `Object`
+  **response**: `Object`
 
 
-## Middleware.next() 
+## Middleware.next()
 
 Allow the hand over to the next middleware object or function.
 

docs/router.md

@@ -1,6 +1,7 @@
 # Router
 
-## Router.use(middleware) 
+
+## Router.use(middleware)
 
 Use the given middleware function or object on this router.
 
@@ -14,12 +15,12 @@ Use the given middleware function or object on this router.
 
 **Parameters**
 
-**middleware**: `Middleware | function`, Middleware object or function
+  **middleware**: `Middleware | function`, Middleware object or function
 
-**Returns**: `Router`, for chaining
+  **Returns**: `Router`, for chaining
 
 
-## Router.all(middleware) 
+## Router.all(middleware)
 
 Use the given middleware function or object on this router for
 all HTTP methods.
@@ -34,6 +35,35 @@ all HTTP methods.
 
 **Parameters**
 
-**middleware**: `Middleware | function`, Middleware object or function
+  **middleware**: `Middleware | function`, Middleware object or function
+
+  **Returns**: `Router`, for chaining
+
+
+## Router.get(uri, middleware), Router.post(uri, middleware)...
+
+Use the given middleware function or object, with optional _uri_ on
+HTTP methods: get, post, put, delete...
+Default _uri_ is "/".
+
+```js
+ // middleware function will be applied on path "/"
+ router.get((req, res, next) => {console.log('Hello')});
+
+ // middleware object will be applied on path "/" and
+ router.get(new Middleware());
+
+ // middleware function will be applied on path "/user"
+ router.post('/user', (req, res, next) => {console.log('Hello')});
+
+ // middleware object will be applied on path "/user" and
+ router.post('/user', new Middleware());
+```
+
+**Parameters**
+
+  **uri**: `String`, path
+
+  **middleware**: `Middleware | function`, Middleware object or function
 
 **Returns**: `Router`, for chaining

lib/application.js

@@ -145,7 +145,7 @@ export default class Application {
      *    app.use(new Middleware());
      *
      * @param {String} uri
-     * @param {Middleware|Function} middleware or fn
+     * @param {Middleware|Function} middleware object or function
      * @return {app} for chaining
      *
      * @public
@@ -372,7 +372,7 @@ HTTP_METHODS.reduce((reqProto, method) => {
      *    // => "bar"
      *
      * @param {String} uri or setting
-     * @param {Middleware|Function} middleware or fn
+     * @param {Middleware|Function} middleware object or function
      * @return {app} for chaining
      * @public
      */

lib/frontexpress.js

@@ -17,7 +17,7 @@ import Middleware from './middleware';
 const frontexpress = () => new Application();
 
 /**
- * Expose constructors.
+ * Expose Router, Middleware constructors.
  */
 frontexpress.Router = (baseUri) => new Router(baseUri);
 frontexpress.Middleware = (name) => new Middleware(name);

lib/middleware.js

@@ -17,7 +17,7 @@ export default class Middleware {
     }
 
     /**
-     * Invoked by the app before ajax request are sent or
+     * Invoked by the app before an ajax request is sent or
      * during the DOM loading (document.readyState === 'loading').
      * See Application#_callMiddlewareEntered documentation for details.
      *
@@ -31,7 +31,7 @@ export default class Middleware {
 
 
     /**
-     * Invoked by the app before a new ajax request is sent or before the DOM unloading.
+     * Invoked by the app before a new ajax request is sent or before the DOM is unloaded.
      * See Application#_callMiddlewareExited documentation for details.
      *
      * Override this method to add your custom behaviour
@@ -44,7 +44,7 @@ export default class Middleware {
 
 
     /**
-     * Invoked on ajax request responding or on DOM ready
+     * Invoked by the app after an ajax request has responded or on DOM ready
      * (document.readyState === 'interactive').
      * See Application#_callMiddlewareUpdated documentation for details.
      *
@@ -59,7 +59,7 @@ export default class Middleware {
 
 
     /**
-     * Invoked when ajax request fails.
+     * Invoked by the app when an ajax request has failed.
      *
      * Override this method to add your custom behaviour
      *

lib/router.js

@@ -197,7 +197,7 @@ export default class Router {
      *    // middleware object
      *    router.use(new Middleware());
      *
-     * @param {Middleware|Function} middleware or fn
+     * @param {Middleware|Function} middleware object or function
      * @return {Router} for chaining
      *
      * @public
@@ -224,7 +224,7 @@ export default class Router {
      *    // middleware object
      *    router.all(new Middleware());
      *
-     * @param {Middleware|Function} middleware or fn
+     * @param {Middleware|Function} middleware object or function
      * @return {Router} for chaining
      *
      * @public
@@ -273,8 +273,8 @@ for (const method of HTTP_METHODS) {
      *    // middleware object will be applied on path "/user" and
      *    router.post('/user', new Middleware());
      *
-     * @param {String} uri or setting
+     * @param {String} uri
-     * @param {Middleware|Function} middleware or fn
+     * @param {Middleware|Function} middleware object or function
      * @return {Router} for chaining
      * @public
      */