define description overrides by version, like examples

scripts/generate/js_api.js

@@ -27,7 +27,8 @@ module.exports = function (branch, done) {
     mergeConcatParams: {},
     paramAsBody: {},
     clientActionModifier: false,
-    examples: {}
+    examples: {},
+    descriptions: {},
   });
 
   var steps = [
@@ -115,12 +116,19 @@ module.exports = function (branch, done) {
     [].concat(apiSpec.actions, apiSpec.proxies)
     .forEach(function (action) {
       var examplePath = overrides.examples[action.name] || action.name + '.asciidoc';
+      var descriptionPath = overrides.descriptions[action.name] || action.name + '.asciidoc';
 
       try {
         action.examples = fs.readFileSync(fromRoot('docs/_examples', examplePath), 'utf8');
       } catch (e) {
         action.examples = '// no examples';
       }
+
+      try {
+        action.description = fs.readFileSync(fromRoot('docs/_descriptions', descriptionPath), 'utf8');
+      } catch (e) {
+        action.description = '// no description';
+      }
     })
 
     done();

scripts/generate/overrides.js

@@ -249,9 +249,6 @@ function (spec) {
         '/_update_by_query/{task_id}/_rethrottle',
         '/_delete_by_query/{task_id}/_rethrottle'
       ]
-    },
-    examples: {
-      scroll: 'scroll_5.0+.asciidoc'
     }
   },
   {
@@ -266,5 +263,31 @@ function (spec) {
         body: 'scroll_id'
       }
     }
+  },
+  // description overrides by major version
+  {
+    version: '0.90.x',
+    descriptions: {
+      search: 'search_1.x.asciidoc'
+    }
+  },
+  {
+    version: '1.x',
+    descriptions: {
+      search: 'search_1.x.asciidoc'
+    }
+  },
+  {
+    version: '2.x',
+    descriptions: {
+      search: 'search_2.x.asciidoc'
+    }
+  },
+  // examples changed at 5.0
+  {
+    version: '<5.0.0',
+    examples: {
+      scroll: 'scroll_<5.0.asciidoc'
+    }
   }
 ];

scripts/generate/templates/api_methods.tmpl

@@ -21,7 +21,7 @@ _.each(actions, function (action) {
 client.<%= action.name %>([params, [callback]])
 --------
 
-<%= description(action.name) %>
+<%= action.description %>
 
 Check the *<<api-conventions>>* and <%= action.docUrl %>[the elasticsearch docs] for more information pertaining to this method.
 

scripts/generate/templates/index.js

@@ -54,18 +54,6 @@ var templateGlobals = {
     return block.split('\n\n').join('\n+\n');
   },
 
-  description: function (action) {
-    try {
-      return fs.readFileSync(path.join(__dirname, '../../../docs/_descriptions/' + action + '.asciidoc'));
-    } catch (e) {
-      if (~e.message.indexOf('ENOENT')) {
-        return '// no description';
-      } else {
-        throw e;
-      }
-    }
-  },
-
   paramType: function (type, paramName) {
     switch (type && type.toLowerCase ? type.toLowerCase() : 'any') {
       case 'time':