[API] Code Generator: Refactors documentation helper functions

Author: picandocodigo

elasticsearch-api/utils/thor/generate_source.rb

@@ -23,6 +23,7 @@
 require 'coderay'
 require 'pry'
 require_relative 'generator/build_hash_helper'
+require_relative 'generator/docs_helper'
 require_relative 'generator/files_helper'
 require_relative './endpoint_spec'
 
@@ -42,6 +43,7 @@ class SourceGenerator < Thor
       namespace 'code'
       include Thor::Actions
       include EndpointSpecifics
+      include DocsHelper
 
       desc 'generate', 'Generate source code and tests from the REST API JSON specification'
       method_option :verbose, type: :boolean, default: false,  desc: 'Output more information'
@@ -65,68 +67,24 @@ def generate_source
         FilesHelper.files.each do |filepath|
           @spec = EndpointSpec.new(filepath)
           say_status 'json', @spec.path, :yellow
-
           # Don't generate code for internal APIs:
           next if @spec.module_namespace.flatten.first == '_internal'
 
           path_to_file = output.join(@spec.module_namespace.join('/')).join("#{@spec.method_name}.rb")
           dir = output.join(@spec.module_namespace.join('/'))
-
           empty_directory(dir, verbose: false)
 
           # Write the file with the ERB template:
           template('templates/method.erb', path_to_file, force: true)
 
+          # Optionals:
           print_source_code(path_to_file) if options[:verbose]
-
           generate_tests if options[:tests]
-
-          puts
         end
-
         run_rubocop
         BuildHashHelper.add_hash(@build_hash)
       end
 
-      def docs_helper(name, info)
-        info['type'] = 'String' if info['type'] == 'enum' # Rename 'enums' to 'strings'
-        info['type'] = 'Integer' if info['type'] == 'int' # Rename 'int' to 'Integer'
-        tipo = info['type'] ? info['type'].capitalize : 'String'
-        description = info['description'] ? info['description'].strip : '[TODO]'
-        options = info['options'] ? "(options: #{info['options'].join(', ').strip})" : nil
-        required = info['required'] ? '(*Required*)' : ''
-        deprecated = info['deprecated'] ? '*Deprecated*' : ''
-        optionals = [required, deprecated, options].join(' ').strip
-
-        "# @option arguments [#{tipo}] :#{name} #{description} #{optionals}\n"
-      end
-
-      def stability_doc_helper(stability)
-        return if stability == 'stable'
-
-        if stability == 'experimental'
-          <<~MSG
-            # This functionality is Experimental and may be changed or removed
-            # completely in a future release. Elastic will take a best effort approach
-            # to fix any issues, but experimental features are not subject to the
-            # support SLA of official GA features.
-          MSG
-        elsif stability == 'beta'
-          <<~MSG
-            # This functionality is in Beta and is subject to change. The design and
-            # code is less mature than official GA features and is being provided
-            # as-is with no warranties. Beta features are not subject to the support
-            # SLA of official GA features.
-          MSG
-        else
-          <<~MSG
-            # This functionality is subject to potential breaking changes within a
-            # minor version, meaning that your referencing code may break when this
-            # library is upgraded.
-          MSG
-        end
-      end
-
       def generate_tests
         copy_file 'templates/test_helper.rb', @output.join('test').join('test_helper.rb')
 

elasticsearch-api/utils/thor/generator/docs_helper.rb

@@ -0,0 +1,62 @@
+# Licensed to Elasticsearch B.V. under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Elasticsearch B.V. licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+module Elasticsearch
+  module API
+    # Helper with file related methods for code generation
+    module DocsHelper
+      def docs(name, info)
+        info['type'] = 'String' if info['type'] == 'enum' # Rename 'enums' to 'strings'
+        info['type'] = 'Integer' if info['type'] == 'int' # Rename 'int' to 'Integer'
+        tipo = info['type'] ? info['type'].capitalize : 'String'
+        description = info['description'] ? info['description'].strip : '[TODO]'
+        options = info['options'] ? "(options: #{info['options'].join(', ').strip})" : nil
+        required = info['required'] ? '(*Required*)' : ''
+        deprecated = info['deprecated'] ? '*Deprecated*' : ''
+        optionals = [required, deprecated, options].join(' ').strip
+
+        "# @option arguments [#{tipo}] :#{name} #{description} #{optionals}\n"
+      end
+
+      def stability_doc_helper(stability)
+        return if stability == 'stable'
+
+        if stability == 'experimental'
+          <<~MSG
+            # This functionality is Experimental and may be changed or removed
+            # completely in a future release. Elastic will take a best effort approach
+            # to fix any issues, but experimental features are not subject to the
+            # support SLA of official GA features.
+          MSG
+        elsif stability == 'beta'
+          <<~MSG
+            # This functionality is in Beta and is subject to change. The design and
+            # code is less mature than official GA features and is being provided
+            # as-is with no warranties. Beta features are not subject to the support
+            # SLA of official GA features.
+          MSG
+        else
+          <<~MSG
+            # This functionality is subject to potential breaking changes within a
+            # minor version, meaning that your referencing code may break when this
+            # library is upgraded.
+          MSG
+        end
+      end
+    end
+  end
+end

elasticsearch-api/utils/thor/templates/_documentation_top.erb

@@ -25,12 +25,12 @@
 <%= '  '*(@spec.namespace_depth+3) %>#
 <%- unless @spec.path_parts.nil? || @spec.path_parts.empty? %><%# URL parts -%>
   <%- @spec.path_parts.each do |name, info| -%>
-    <%= docs_helper(name, info) -%>
+    <%= docs(name, info) -%>
   <%- end -%>
 <%- end -%><%# Body -%>
 <%# URL parameters -%>
 <%- @spec.params.each do |name, info| -%>
-  <%= docs_helper(name, info) unless ([email protected]_parts.empty? && @spec.path_parts.keys.include?(name)) -%>
+  <%= docs(name, info) unless ([email protected]_parts.empty? && @spec.path_parts.keys.include?(name)) -%>
 <%- end -%>
 # @option arguments [Hash] :headers Custom HTTP headers
 <%- if @spec.body -%>