Made tweaks to the middleware documentation (#474)

Author: sudohogan

language/en.yml

@@ -344,68 +344,68 @@ middlewares:
     post: "Postprocessing and validation step"
     encoding:
       title: "JSON and form encode"
-      description: "This middleware encodes request bodies automatically and sets the appropriate header."
-      pre: "Here the encoding property on the route gets processed."
-      post: "This is a noop, so no functionality."
+      description: "This middleware automatically encodes request bodies (JSON or form data) and sets the correct Content-Type header. It is a quick prep step before sending HTTP requests."
+      pre: "Here it checks if the reequest.autohandle field is set to either 'JSON' or 'form'. If JSON, the Content-Type is set to application/json, else if set to form then Content-Type is set to application/x-www-form-urlencoded. If autohandle is missing, it sends the request unmodified."
+      post: "This is a no-op(no operation), so no functionality."
     access:
-      title: "access token handling"
+      title: "Access Token handling"
       description: "This handles bearer tokens, including JWTs retrieval and setting in common response structured."
       pre: "Adds an access token if it's available as Bearer Token."
-      post: "Tries to retrieve an access token from a JSON response. It has multiple fallbacks to cover common naming schemes."
+      post: "Tries to retrieve an access token from a JSON response. It has multiple fallbacks to cover common naming schemes like 'access', 'access-token' & 'access_token', 'refresh', 'refresh-token' & 'refresh_token'."
     csrf:
-      title: "csrf-header handling"
+      title: "CSRF-header Handling"
       description: "This middleware handles cross site request forgery tokens build in common manners."
-      pre: "This will add a CSRF header if any data for it has been retrieved."
+      pre: "This will automatically add a CSRF header if any data for it has been retrieved."
       post: "This will try to retrieve a new CSRF token from the response. It may not catch all, since implementations vary widely."
     2xx:
-      title: "status 2xx check"
-      description: "This is a validator for the HTTP status code."
-      pre: "This is a noop, so no functionality."
-      post: "This will fail if the status code of the response is less than 200 or bigger than 299."
+      title: "Status Code 2xx Check"
+      description: "This middleware validates that HTTP responses have status codes in the 200-299 range (successful responses). It acts as a quality gate to ensure your application only processes successful API responses."
+      pre: "This is a no-op(no operation), so no functionality."
+      post: "This will fail if the status code of the response is undefined, less than 200 or higher than 299."
     403:
-      title: "status 403 check"
-      description: "This is a validator for the HTTP status code."
-      pre: "This is a noop, so no functionality."
-      post: "This will fail if the status code of the response is different from 403."
+      title: "Status Code 403 Check"
+      description: "This is a specialized middleware to verify status code 403 responses."
+      pre: "This is a no-op(no operation), so no functionality."
+      post: "This will verify that a response status is exactly 403 (Forbidden) and throws a descriptive error if the response is missing a status code or if the status code isn't 403."
     404:
-      title: "status 404 check"
-      description: "This is a validator for the HTTP status code."
-      pre: "This is a noop, so no functionality."
-      post: "This will fail if the status code of the response is different from 404."
+      title: "Status Code 404 Check"
+      description: "This is a specialized middleware to verify status code 404 responses."
+      pre: "This is a no-op(no operation), so no functionality."
+      post: "This will verify that a response status is exactly 404 (Not Found) and throws a descriptive error if the response is missing a status code or if the status code isn't 404."
     user-agent:
-      title: "user-agent"
+      title: "User-Agent"
       description: "This sets a sensible user agent string, so it can easily be filtered out for logging."
-      pre: "The user agent string will be added, based on the used versions of the project and the framework."
-      post: "This is a noop, so no functionality."
+      pre: "The user agent string will be added, based on the used versions of the project and the framework. It doesn't overwrite existing User-Agent headers."
+      post: "This is a no-op(no operation), so no functionality."
     cookies:
-      title: "cookies"
+      title: "Cookies"
       description: "This middleware handles cookies sent via headers."
-      pre: "This function sets all available cookies on the request."
-      post: "This function retrieves all available cookies from the response."
+      pre: "This adds all stored cookies to the request, it preserves existing request cookies (no overwrites)."
+      post: "This function retrieves all available cookies from successful responses, updates cookie store with new values."
     json:
-      title: "json-validator"
-      description: "This validator checks for valid header and body content."
-      pre: "This is a noop, so no functionality."
-      post: "This will fail if no json was returned."
+      title: "JSON-validator"
+      description: "This validator checks for valid JSON in header and body response."
+      pre: "This is a no-op(no operation), so no functionality."
+      post: "This will confirm if the Content-Type header exists, validates if header matches application/json (case-insensitive), fails if no json was returned."
     xml:
-      title: "xml-validator"
-      description: "This validator checks for valid header and body content."
-      pre: "This is a noop, so no functionality."
-      post: "This will fail if no xml was returned."
+      title: "XML-validator"
+      description: "This validator checks for valid XML in header and body content."
+      pre: "This is a no-op(no operation), so no functionality."
+      post: "This will confirm existence of Content-Type header, validates header contains /xml (case-insensitive) supports variants like 'application/xml', 'text/xml' & 'application/atom+xml'. Fails if no xml was returned."
     silent-server-validator:
       title: "silent-server-validator"
-      description: "This middleware tries to help keep servers a bit safer."
-      pre: "This is a noop, so no functionality."
-      post: "If the server discloses information about itself or the language used server-side, this will fail."
+      description: "This middleware tries to detect leaks and help keep servers a bit safer."
+      pre: "This is a no-op(no operation), so no functionality."
+      post: "This checks if the server discloses information about itself (e.g Apache, nginx, IIS etc.) or the language used server-side (e.g PHP, Express, ASP.NET etc.), if it does then this will fail."
     success-check:
-      title: "check response for success"
+      title: "Check Response for Success"
       description: "This assumes a json response with a boolean or string status following common standards."
-      pre: "This is a noop, so no functionality."
+      pre: "This is a no-op(no operation), so no functionality."
       post: "If the success field is not there or not a know positive this will fail."
     failure-check:
-      title: "check response for failure"
+      title: "Check Response for Failure"
       description: "This assumes a json response with a boolean or string status following common standards."
-      pre: "This is a noop, so no functionality."
+      pre: "This is a no-op(no operation), so no functionality."
       post: "If the success field is not there or not a know negative this will fail."
   custom:
     title: "Custom Middleware"