Document the extension params behavior. Fixes #966.

API.md

@@ -389,6 +389,11 @@ Extension objects use the following parameters :
 
 Factory functions are advised if you intend to publish your extensions for others to use, because they are capable of using an extended joi being built, thus avoiding any erasure when using multiple extensions at the same time. See an example of a factory function in the section below.
 
+THe `params` of `rules` rely on the fact that all engines, even though not stated in the ECMA specifications, preserve the order of object keys, this is a conscious choice to simplify the API for the end-user. If you ever see an engine misbehaving or are uncomfortable relying on this, you can use a single option object to describe your parameters, like:
+```js
+params: { options: Joi.object({ param1: Joi.number().required(), param2: Joi.string() }) }
+```
+
 Any of the `coerce`, `pre` and `validate` functions should use `this.createError(type, context, state, options[, flags])` to create and return errors.
 This function potentially takes 5 arguments:
 * `type` - the dotted type of the error matching predefined language elements or the ones defined in your extension. **Required**.