puppet-strings 2.3.0 → 2.7.0

data/lib/puppet-strings/markdown/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings'
 require 'puppet-strings/json'
 require 'puppet-strings/yard'
@@ -68,7 +70,7 @@ module PuppetStrings::Markdown
 
     # @return [String] top-level name
     def name
-      @registry[:name].to_s unless @registry[:name].nil?
+      @registry[:name]&.to_s
     end
 
     # @return [String] 'Overview' text (untagged text)
@@ -111,6 +113,11 @@ module PuppetStrings::Markdown
       select_tags('option')
     end
 
+    # @return [Array] enum tag hashes
+    def enums
+      select_tags('enum')
+    end
+
     # @param parameter_name
     #   parameter name to match to option tags
     # @return [Array] option tag hashes that have a parent parameter_name
@@ -119,6 +126,14 @@ module PuppetStrings::Markdown
       opts_for_p unless opts_for_p.nil? || opts_for_p.length.zero?
     end
 
+    # @param parameter_name
+    #   parameter name to match to enum tags
+    # @return [Array] enum tag hashes that have a parent parameter_name
+    def enums_for_param(parameter_name)
+      enums_for_p = enums.select { |e| e[:parent] == parameter_name } unless enums.nil?
+      enums_for_p unless enums_for_p.nil? || enums_for_p.length.zero?
+    end
+
     # @return [Hash] any defaults found for the component
     def defaults
       @registry[:defaults] unless @registry[:defaults].nil?
@@ -156,10 +171,22 @@ module PuppetStrings::Markdown
       @tags.any? { |tag| tag[:tag_name] == 'api' && tag[:text] == 'private' }
     end
 
+    def word_wrap(text, line_width: 120, break_sequence: "\n")
+      return unless text
+
+      text.split("\n").collect! do |line|
+        line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1#{break_sequence}").strip : line
+      end * break_sequence
+    end
+
     # @return [String] full markdown rendering of a component
     def render(template)
-      file = File.join(File.dirname(__FILE__),"templates/#{template}")
-      ERB.new(File.read(file), nil, '-').result(binding)
+      begin
+        file = File.join(File.dirname(__FILE__),"templates/#{template}")
+        ERB.new(File.read(file), nil, '-').result(binding)
+      rescue StandardError => e
+        fail "Processing #{@registry[:file]}:#{@registry[:line]} with #{file} => #{e}"
+      end
     end
 
     private

data/lib/puppet-strings/markdown/data_type.rb

@@ -1,18 +1,36 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
   # This class encapsualtes ruby data types and puppet type aliases
   class DataType < Base
     attr_reader :alias_of
+    attr_reader :functions
 
     def initialize(registry)
       @template = 'data_type.erb'
       super(registry, 'data type')
       @alias_of = registry[:alias_of] unless registry[:alias_of].nil?
+      @functions = @registry[:functions].nil? ? nil : @registry[:functions].map { |func| DataType::Function.new(func) }
     end
 
     def render
       super(@template)
     end
   end
+
+  class DataType::Function < Base
+    def initialize(registry)
+      super(registry, 'data_type_function')
+    end
+
+    def render
+      super('data_type_function.erb')
+    end
+
+    def signature
+      @registry[:signature]
+    end
+  end
 end

data/lib/puppet-strings/markdown/data_types.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'data_type'
 
 module PuppetStrings::Markdown
@@ -22,7 +24,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_dtypes.length > 0 ? "## Data types\n\n" : ""
       in_dtypes.each do |type|
-        final << type.render unless type.private?
+        final += type.render unless type.private?
       end
       final
     end

data/lib/puppet-strings/markdown/defined_type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

data/lib/puppet-strings/markdown/defined_types.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'defined_type'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_dtypes.length > 0 ? "## Defined types\n\n" : ""
       in_dtypes.each do |type|
-        final << type.render unless type.private?
+        final += type.render unless type.private?
       end
       final
     end

data/lib/puppet-strings/markdown/function.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
@@ -19,23 +21,23 @@ module PuppetStrings::Markdown
 
     def type
       t = @registry[:type]
-      if t =~ /ruby4x/
+      if /ruby4x/.match?(t)
         "Ruby 4.x API"
-      elsif t =~ /ruby3/
+      elsif /ruby3/.match?(t)
         "Ruby 3.x API"
-      elsif t =~ /ruby/
+      elsif /ruby/.match?(t)
         "Ruby"
       else
         "Puppet Language"
       end
     end
 
-    def error_type(r) # rubocop:disable Naming/UncommunicativeMethodParamName
-      "`#{r.split(' ')[0]}`"
+    def error_type(type)
+      "`#{type.split(' ')[0]}`"
     end
 
-    def error_text(r) # rubocop:disable Naming/UncommunicativeMethodParamName
-      "#{r.split(' ').drop(1).join(' ')}"
+    def error_text(text)
+      "#{text.split(' ').drop(1).join(' ')}"
     end
   end
 

data/lib/puppet-strings/markdown/functions.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'function'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_functions.length > 0 ? "## Functions\n\n" : ""
       in_functions.each do |func|
-        final << func.render unless func.private?
+        final += func.render unless func.private?
       end
       final
     end

data/lib/puppet-strings/markdown/puppet_class.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

data/lib/puppet-strings/markdown/puppet_classes.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'puppet_class'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_classes.length > 0 ? "## Classes\n\n" : ""
       in_classes.each do |klass|
-        final << klass.render unless klass.private?
+        final += klass.render unless klass.private?
       end
       final
     end

data/lib/puppet-strings/markdown/puppet_plan.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

data/lib/puppet-strings/markdown/puppet_plans.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'puppet_plan'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_plans.length > 0 ? "## Plans\n\n" : ""
       in_plans.each do |plan|
-        final << plan.render unless plan.private?
+        final += plan.render unless plan.private?
       end
       final
     end

data/lib/puppet-strings/markdown/puppet_task.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

data/lib/puppet-strings/markdown/puppet_tasks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'puppet_task'
 
 module PuppetStrings::Markdown
@@ -16,7 +18,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_tasks.length > 0 ? "## Tasks\n\n" : ""
       in_tasks.each do |task|
-        final << task.render unless task.private?
+        final += task.render unless task.private?
       end
       final
     end

data/lib/puppet-strings/markdown/resource_type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
@@ -12,11 +14,28 @@ module PuppetStrings::Markdown
     end
 
     def properties
-      @registry[:properties]
+      return nil unless @registry[:properties]
+
+      @registry[:properties].sort_by { |p| p[:name] }
+    end
+
+    def checks
+      return nil unless @registry[:checks]
+
+      @registry[:checks].sort_by { |p| p[:name] }
+    end
+
+    # "checks" (such as "onlyif" or "creates") are another type of property
+    def properties_and_checks
+      return nil if properties.nil? && checks.nil?
+
+      ((properties || []) + (checks || [])).sort_by { |p| p[:name] }
     end
 
     def parameters
-      @registry[:parameters]
+      return nil unless @registry[:parameters]
+
+      @registry[:parameters].sort_by { |p| p[:name] }
     end
 
     def regex_in_data_type?(data_type)

data/lib/puppet-strings/markdown/resource_types.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'resource_type'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_rtypes.length > 0 ? "## Resource types\n\n" : ""
       in_rtypes.each do |type|
-        final << type.render unless type.private?
+        final += type.render unless type.private?
       end
       final
     end

data/lib/puppet-strings/markdown/table_of_contents.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PuppetStrings::Markdown
   module TableOfContents
     def self.render
@@ -16,7 +18,7 @@ module PuppetStrings::Markdown
         priv = r.contains_private?
 
         template = File.join(File.dirname(__FILE__),"templates/table_of_contents.erb")
-        final << ERB.new(File.read(template), nil, '-').result(binding)
+        final += ERB.new(File.read(template), nil, '-').result(binding)
       end
       final
     end

data/lib/puppet-strings/markdown/templates/classes_and_defines.erb

@@ -1,4 +1,4 @@
-### <%= name %>
+### <a name="<%= link %>"></a>`<%= name %>`
 
 <% if text -%>
 <%= text %>
@@ -24,10 +24,10 @@
 * **See also**
 <% see.each do |sa| -%>
 <% if sa[:name] -%>
-<%= sa[:name] %>
+<%= "  * #{sa[:name]}" %>
 <% end -%>
 <% if sa[:text] -%>
-<%= sa[:text] %>
+  <%= "  * #{sa[:text]}" %>
 <% end -%>
 <% end -%>
 
@@ -47,10 +47,14 @@
 <% if params -%>
 #### Parameters
 
-The following parameters are available in the `<%= name %>` <%= @type %>.
+The following parameters are available in the `<%= name %>` <%= @type %>:
 
 <% params.each do |param| -%>
-##### `<%= param[:name] %>`
+* [`<%= param[:name] %>`](#<%= param[:name] %>)
+<% end -%>
+
+<% params.each do |param| -%>
+##### <a name="<%= param[:name] %>"></a>`<%= param[:name] %>`
 
 <% if param[:types] -%>
 Data type: `<%= param[:types].join(', ') -%>`
@@ -65,9 +69,17 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% if defaults && defaults[param[:name]] -%>
-Default value: <%= value_string(defaults[param[:name]]) %>
+Default value: `<%= value_string(defaults[param[:name]]) %>`
 
 <% end -%>
 <% end -%>

data/lib/puppet-strings/markdown/templates/data_type.erb

@@ -1,4 +1,4 @@
-### <%= name %>
+### <a name="<%= link %>"></a>`<%= name %>`
 
 <% if text -%>
 <%= text %>
@@ -24,10 +24,10 @@
 * **See also**
 <% see.each do |sa| -%>
 <% if sa[:name] -%>
-<%= sa[:name] %>
+<%= "  * #{sa[:name]}" %>
 <% end -%>
 <% if sa[:text] -%>
-<%= sa[:text] %>
+<%= "  * #{sa[:text]}" %>
 <% end -%>
 <% end -%>
 
@@ -45,16 +45,24 @@
 <% end -%>
 <% end -%>
 <% if alias_of -%>
-Alias of `<%= alias_of %>`
+Alias of
+
+```puppet
+<%= alias_of %>
+```
 
 <% end -%>
 <% if params -%>
 #### Parameters
 
-The following parameters are available in the `<%= name %>` <%= @type %>.
+The following parameters are available in the `<%= name %>` <%= @type %>:
 
 <% params.each do |param| -%>
-##### `<%= param[:name] %>`
+* [`<%= param[:name] %>`](#<%= param[:name] %>)
+<% end -%>
+
+<% params.each do |param| -%>
+##### <a name="<%= param[:name] %>"></a>`<%= param[:name] %>`
 
 <% if param[:types] -%>
 Data type: `<%= param[:types].join(', ') -%>`
@@ -69,10 +77,25 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% if defaults && defaults[param[:name]] -%>
-Default value: <%= value_string(defaults[param[:name]]) %>
+Default value: `<%= value_string(defaults[param[:name]]) %>`
 
 <% end -%>
 <% end -%>
 <% end -%>
+<% if functions -%>
+#### Functions
+
+The following functions are available in the `<%= name %>` <%= @type %>.
+
+<% functions.each do |func| -%><%= func.render -%><% end -%>
+<% end -%>