From 9fee381c8e9dc211085ee61ffde0a0b58825368b Mon Sep 17 00:00:00 2001
From: spalger <email@spalger.com>
Date: Wed, 16 Nov 2016 18:12:41 -0700
Subject: [PATCH] [docs] add more detailed type information for parameters

---
 docs/api_param_types.asciidoc               | 23 +++++++++++++++++++++
 scripts/generate/templates/api_methods.tmpl |  2 +-
 scripts/generate/templates/docs_index.tmpl  |  2 ++
 scripts/generate/templates/index.js         | 22 +++++++++++++-------
 4 files changed, 41 insertions(+), 8 deletions(-)
 create mode 100644 docs/api_param_types.asciidoc

diff --git a/docs/api_param_types.asciidoc b/docs/api_param_types.asciidoc
new file mode 100644
index 000000000..d3b2c7ccc
--- /dev/null
+++ b/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.
diff --git a/scripts/generate/templates/api_methods.tmpl b/scripts/generate/templates/api_methods.tmpl
index af20925a9..c7cecd050 100644
--- a/scripts/generate/templates/api_methods.tmpl
+++ b/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:::')
diff --git a/scripts/generate/templates/docs_index.tmpl b/scripts/generate/templates/docs_index.tmpl
index bad7fb953..a96b38a3d 100644
--- a/scripts/generate/templates/docs_index.tmpl
+++ b/scripts/generate/templates/docs_index.tmpl
@@ -36,3 +36,5 @@ include::host.asciidoc[]
 include::transport.asciidoc[]
 
 include::errors.asciidoc[]
+
+include::api_param_types.asciidoc[]
\ No newline at end of file
diff --git a/scripts/generate/templates/index.js b/scripts/generate/templates/index.js
index c450076d8..f23a8d59f 100644
--- a/scripts/generate/templates/index.js
+++ b/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}"`);
     }
   },