[docs] add more detailed type information for parameters

docs/api_param_types.asciidoc

@@ -0,0 +1,23 @@
+[[api-param-types]]
+== API Param Types
+
+The <<api-reference>> describes the type that each parameter accepts, this reference describes each of those types in more a little more detail.
+
+[horizontal]
+`Boolean`[[api-param-type-boolean]]:: -- `true` or `false`.
+
+`Number`[[api-param-type-number]]:: -- A basic JavaScript number.
+
+`String`[[api-param-type-string]]:: -- A basic JavaScript https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String[String].
+
+`String[]`[[api-param-type-string-array]]:: -- An array of strings.
+
+`Object`[[api-param-type-object]]:: -- A JSON serializable object.
+
+`Object[]`[[api-param-type-object-array]]:: -- An array of JSON serializable objects.
+
+`JSON`[[api-param-type-json]]:: -- A string or `Buffer` containing a serialized JSON object.
+
+`JSONLines`[[api-param-type-json-lines]]:: -- A string or `Buffer` of new-line (`\n`) delimited JSON objects.
+
+`DurationString`[[api-param-type-duration-string]]:: -- A string that represents a duration of time with a number followed by an https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#time-units[elasticsearch time unit]. `30m` is thirty minutes, `2d` is two days, and so on.

scripts/generate/templates/api_methods.tmpl

@@ -37,7 +37,7 @@ var printParam = function (param, paramName) {
   print(`\n\`${paramWithDefault(paramName, param.default)}\`::`)
   
   // param type and description
-  print(`\n\`${paramType(param.type, paramName)}\` -- ${joinParagraphs(param.description || '', 4)}`)
+  print(`\n${paramType(param.type, paramName)} -- ${joinParagraphs(param.description || '', 4)}`)
   
   if (param.type === 'enum') {
     print('\nOptions:::')

scripts/generate/templates/docs_index.tmpl

@@ -36,3 +36,5 @@ include::host.asciidoc[]
 include::transport.asciidoc[]
 
 include::errors.asciidoc[]
+
+include::api_param_types.asciidoc[]

scripts/generate/templates/index.js

@@ -69,20 +69,28 @@ var templateGlobals = {
   paramType: function (type, paramName) {
     switch (type && type.toLowerCase ? type.toLowerCase() : 'any') {
       case 'time':
+      case 'duration':
         if (paramName === 'timestamp') return 'Timestamp'
-        return 'DurationString';
+        return '<<api-param-type-duration-string,`DurationString`>>';
       case 'any':
-        return 'Anything';
+        return 'anything';
       case 'enum':
-        return 'String';
+      case 'string':
+      case 'text':
+        return '<<api-param-type-string,`String`>>';
+      case 'boolean':
+        return '<<api-param-type-boolean,`Boolean`>>';
+      case 'number':
+      case 'integer':
+        return '<<api-param-type-number,`Number`>>';
       case 'list':
-        return 'String, String[], Boolean';
+        return '<<api-param-type-string,`String`>>, <<api-param-type-string-array,`String[]`>>, <<api-param-type-boolean,`Boolean`>>';
       case 'bulkbody':
-        return 'Object[], JSONLines';
+        return '<<api-param-type-object-array,`Object[]`>>, <<api-param-type-json-lines,`JSONLines`>>';
       case 'body':
-        return 'Object, JSON';
+        return '<<api-param-type-object,`Object`>>, <<api-param-type-json,`JSON`>>';
       default:
-        return _.ucfirst(type);
+        throw new Error(`unknown type "${type}"`);
     }
   },