puppet-strings 2.4.0 → 2.8.0

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

@@ -1,4 +1,4 @@
-### <%= name %>
+### <a name="<%= link %>"></a>`<%= name %>`
 
 <% if text -%>
 <%= text %>

data/lib/puppet-strings/markdown/templates/resource_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 -%>
 
@@ -44,16 +44,16 @@
 
 <% end -%>
 <% end -%>
-<% if properties -%>
+<% if properties_and_checks -%>
 #### Properties
 
 The following properties are available in the `<%= name %>` <%= @type %>.
 
-<% properties.each do |prop| -%>
+<% properties_and_checks.each do |prop| -%>
 ##### `<%= prop[:name] %>`
 
 <% if prop[:values] -%>
-Valid values: <%= prop[:values].map { |value| value_string(value) }.join(', ') %>
+Valid values: `<%= prop[:values].map { |value| value_string(value) }.join('`, `') %>`
 
 <% end -%>
 <% if prop[:isnamevar] -%>
@@ -61,7 +61,7 @@ namevar
 
 <% end -%>
 <% if prop[:aliases] -%>
-Aliases: <%= prop[:aliases].to_s.delete('{').delete('}') %>
+Aliases: `<%= prop[:aliases].to_s.delete('{').delete('}') %>`
 
 <% end -%>
 <% if prop[:data_type] -%>
@@ -87,7 +87,7 @@ Options:
 
 <% end -%>
 <% if prop[:default] -%>
-Default value: <%= prop[:default] %>
+Default value: `<%= prop[:default] %>`
 
 <% end -%>
 <% end -%>
@@ -98,10 +98,14 @@ Default value: <%= prop[:default] %>
 The following parameters are available in the `<%= name %>` <%= @type %>.
 
 <% parameters.each do |param| -%>
-##### `<%= param[:name] %>`
+* [`<%= param[:name] %>`](#<%= param[:name] %>)
+<% end -%>
+
+<% parameters.each do |param| -%>
+##### <a name="<%= param[:name] %>"></a>`<%= param[:name] %>`
 
 <% if param[:values] -%>
-Valid values: <%= param[:values].map { |value| value_string(value) }.join(', ') %>
+Valid values: `<%= param[:values].map { |value| value_string(value) }.join('`, `') %>`
 
 <% end -%>
 <% if param[:isnamevar] -%>
@@ -109,14 +113,16 @@ namevar
 
 <% end -%>
 <% if param[:aliases] -%>
-Aliases: <%= param[:aliases].to_s.delete('{').delete('}') %>
+Aliases: `<%= param[:aliases].to_s.delete('{').delete('}') %>`
 
 <% end -%>
 <% if param[:data_type] -%>
 Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(param[:data_type]) %>
 
 <% end -%>
-<%= param[:description] %>
+<% if param[:description] -%>
+<%= word_wrap(param[:description]) %>
+<% end -%>
 
 <% if options_for_param(param[:name]) -%>
 Options:
@@ -135,7 +141,7 @@ Options:
 
 <% end -%>
 <% if param[:default] -%>
-Default value: <%= value_string(param[:default]) %>
+Default value: `<%= value_string(param[:default]) %>`
 
 <% end -%>
 <% if param[:required_features] -%>

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

@@ -1,25 +1,25 @@
 <% if group.length > 0 -%>
-**<%= group_name %>**
+### <%= group_name %>
 
 <% if priv -%>
-_Public <%= group_name %>_
+#### Public <%= group_name %>
 
 <% group.each do |item| -%>
 <% unless item[:private] -%>
-* [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %>
+* [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
 
-_Private <%= group_name %>_
+#### Private <%= group_name %>
 
 <% group.each do |item| -%>
 <% if item[:private] -%>
-* `<%= item[:name] %>`: <%= item[:desc] %>
+* `<%= item[:name] %>`<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
 <% else -%>
 <% group.each do |item| -%>
-* [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %>
+* [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
 

data/lib/puppet-strings/monkey_patches/display_object_command.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Monkey patch URL decoding in object displays. Usually :: is interpreted as a
 # namespace, but this is disabled in our base object, and so instead gets
 # URL-encoded.

data/lib/puppet-strings/tasks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rake'
 require 'rake/tasklib'
 

data/lib/puppet-strings/tasks/generate.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings'
 
 # Implements the strings:generate task.

data/lib/puppet-strings/tasks/gh_pages.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/tasks'
 
 namespace :strings do
@@ -5,6 +7,7 @@ namespace :strings do
     task :checkout do
       if Dir.exist?('doc')
         fail "The 'doc' directory (#{File.expand_path('doc')}) is not a Git repository! Remove it and run the Rake task again." unless Dir.exist?('doc/.git')
+
         Dir.chdir('doc') do
           system 'git checkout gh-pages'
           system 'git pull --rebase origin gh-pages'

data/lib/puppet-strings/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PuppetStrings
-  VERSION = '2.4.0'.freeze
+  VERSION = '2.8.0'
 end

data/lib/puppet-strings/yard.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'yard'
 
 # Module for YARD related functionality.
@@ -102,6 +104,7 @@ class YARD::CLI::Stats
 
   def stats_for_puppet_plans
     return unless PuppetStrings.puppet_5?
+
     output 'Puppet Plans', *type_statistics_all(:puppet_plan)
   end
 

data/lib/puppet-strings/yard/code_objects.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # The module for custom YARD code objects.
 module PuppetStrings::Yard::CodeObjects
   require 'puppet-strings/yard/code_objects/class'

data/lib/puppet-strings/yard/code_objects/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Implements the base code object.
 class PuppetStrings::Yard::CodeObjects::Base < YARD::CodeObjects::NamespaceObject
   # Allocates a new code object.

data/lib/puppet-strings/yard/code_objects/class.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects/group'
 
 # Implements the group for Puppet classes.
@@ -52,8 +54,8 @@ class PuppetStrings::Yard::CodeObjects::Class < PuppetStrings::Yard::CodeObjects
     hash[:inherits] = statement.parent_class if statement.parent_class
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
     defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
-    hash[:defaults] = defaults unless defaults.empty?
-    hash[:source] = source unless source && source.empty?
+    hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
+    hash[:source] = source unless source.nil? || source.empty?
     hash
   end
 end

data/lib/puppet-strings/yard/code_objects/data_type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects/group'
 require 'puppet-strings/yard/util'
 
@@ -24,7 +26,6 @@ class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObje
   # @return [void]
   def initialize(name)
     super(PuppetStrings::Yard::CodeObjects::DataTypes.instance, name)
-    @parameters = []
     @defaults = {}
   end
 
@@ -41,10 +42,6 @@ class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObje
     nil
   end
 
-  def parameter_exist?(name)
-    !docstring.tags(:param).find { |item| item.name == name }.nil?
-  end
-
   def add_parameter(name, type, default)
     tag = docstring.tags(:param).find { |item| item.name == name }
     if tag.nil?
@@ -65,6 +62,24 @@ class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObje
     docstring.tags(:param).map { |tag| [tag.name, defaults[tag.name]] }
   end
 
+  def add_function(name, return_type, parameter_types)
+    meth_obj = YARD::CodeObjects::MethodObject.new(self, name, :class)
+
+    # Add return tag
+    meth_obj.add_tag(YARD::Tags::Tag.new(:return, '', return_type))
+
+    # Add parameters
+    parameter_types.each_with_index do |param_type, index|
+      meth_obj.add_tag(YARD::Tags::Tag.new(:param, '', [param_type], "param#{index + 1}"))
+    end
+
+    self.meths << meth_obj
+  end
+
+  def functions
+    meths
+  end
+
   # Converts the code object to a hash representation.
   # @return [Hash] Returns a hash representation of the code object.
   def to_hash
@@ -72,9 +87,16 @@ class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObje
     hash[:name] = name
     hash[:file] = file
     hash[:line] = line
-    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
-    hash[:defaults] = defaults unless defaults.empty?
-    hash[:source] = source unless source && source.empty?
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring, %i[param option enum return example])
+    hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
+    hash[:source] = source unless source.nil? || source.empty?
+    hash[:functions] = functions.map do |func|
+      {
+        name: func.name,
+        signature: func.signature,
+        docstring: PuppetStrings::Yard::Util.docstring_to_hash(func.docstring, %i[param option enum return example])
+      }
+    end
     hash
   end
 end

data/lib/puppet-strings/yard/code_objects/data_type_alias.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects/group'
 require 'puppet-strings/yard/util'
 

data/lib/puppet-strings/yard/code_objects/defined_type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects/group'
 
 # Implements the group for Puppet defined types.
@@ -51,8 +53,8 @@ class PuppetStrings::Yard::CodeObjects::DefinedType < PuppetStrings::Yard::CodeO
     hash[:line] = line
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
     defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
-    hash[:defaults] = defaults unless defaults.empty?
-    hash[:source] = source unless source && source.empty?
+    hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
+    hash[:source] = source unless source.nil? || source.empty?
     hash
   end
 end

data/lib/puppet-strings/yard/code_objects/function.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects/group'
 
 # Implements the group for Puppet functions.
@@ -61,11 +63,12 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
   # @return [String] Returns the Puppet signature of the function.
   def signature
     return '' if self.has_tag? :overload
+
     tags = self.tags(:param)
     args = @parameters.map do |parameter|
       name, default = parameter
       tag = tags.find { |t| t.name == name } if tags
-      type = tag && tag.types ? "#{tag.type} " : 'Any '
+      type = tag&.types ? "#{tag.type} " : 'Any '
       prefix = "#{name[0]}" if name.start_with?('*', '&')
       name = name[1..-1] if prefix
       default = " = #{default}" if default
@@ -96,8 +99,8 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
 
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
     defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
-    hash[:defaults] = defaults unless defaults.empty?
-    hash[:source] = source unless source && source.empty?
+    hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
+    hash[:source] = source unless source.nil? || source.empty?
     hash
   end
 end

data/lib/puppet-strings/yard/code_objects/group.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects/base'
 
 # Implements the base class for "groups".
@@ -10,6 +12,7 @@ class PuppetStrings::Yard::CodeObjects::Group < PuppetStrings::Yard::CodeObjects
   def self.instance(key)
     instance = P(:root, key)
     return instance unless instance.is_a?(YARD::CodeObjects::Proxy)
+
     instance = self.new(:root, key)
     instance.visibility = :hidden
     P(:root).children << instance

data/lib/puppet-strings/yard/code_objects/plan.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects/group'
 
 class PuppetStrings::Yard::CodeObjects::Plans < PuppetStrings::Yard::CodeObjects::Group
@@ -49,8 +51,8 @@ class PuppetStrings::Yard::CodeObjects::Plan < PuppetStrings::Yard::CodeObjects:
     hash[:line] = line
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
     defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
-    hash[:defaults] = defaults unless defaults.empty?
-    hash[:source] = source unless source && source.empty?
+    hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
+    hash[:source] = source unless source.nil? || source.empty?
     hash
   end
 end

data/lib/puppet-strings/yard/code_objects/provider.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects/group'
 
 # Implements the group for Puppet providers.
@@ -42,6 +44,7 @@ class PuppetStrings::Yard::CodeObjects::Provider < PuppetStrings::Yard::CodeObje
   # @return [void]
   def add_confine(key, value)
     return unless key && value
+
     @confines ||= {}
     @confines[key] = value
   end
@@ -51,6 +54,7 @@ class PuppetStrings::Yard::CodeObjects::Provider < PuppetStrings::Yard::CodeObje
   # @return [void]
   def add_feature(feature)
     return unless feature
+
     @features ||= []
     @features << feature
   end
@@ -60,6 +64,7 @@ class PuppetStrings::Yard::CodeObjects::Provider < PuppetStrings::Yard::CodeObje
   # @return [void]
   def add_default(constraints)
     return unless constraints
+
     @defaults ||= []
     @defaults << constraints
   end
@@ -70,6 +75,7 @@ class PuppetStrings::Yard::CodeObjects::Provider < PuppetStrings::Yard::CodeObje
   # @return [void]
   def add_command(key, value)
     return unless key && value
+
     @commands ||= {}
     @commands[key] = value
   end

data/lib/puppet-strings/yard/code_objects/task.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects/group'
 
 # Implements the group for Puppet tasks.

data/lib/puppet-strings/yard/code_objects/type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects/group'
 require 'puppet-strings/yard/util'
 
@@ -73,6 +75,9 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
   class Property < Parameter
   end
 
+  class Check < Parameter
+  end
+
   # Represents a resource type feature.
   class Feature
     attr_reader :name, :docstring
@@ -95,7 +100,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
     end
   end
 
-  attr_reader :properties, :parameters, :features
+  attr_reader :properties, :features, :checks
 
   # Initializes a new resource type.
   # @param [String] name The resource type name.
@@ -134,17 +139,57 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
     @features << feature
   end
 
+  # Adds a check to the resource type.
+  # @param [PuppetStrings::Yard::CodeObjects::Type::Check] check The check to add.
+  # @return [void]
+  def add_check(check)
+    @checks ||= []
+    @checks << check
+  end
+
+  def parameters
+    # just return params if there are no providers
+    return @parameters if providers.empty?
+
+    # return existing params if we have already added provider
+    return @parameters if @parameters&.any? { |p| p.name == 'provider' }
+
+    provider_param = Parameter.new(
+      'provider',
+      "The specific backend to use for this `#{self.name.to_s}` resource. You will seldom need " + \
+      "to specify this --- Puppet will usually discover the appropriate provider for your platform."
+    )
+
+    @parameters ||= []
+    @parameters << provider_param
+  end
+
+  # Not sure if this is where this belongs or if providers should only be resolved at
+  # render-time. For now, this should re-resolve on every call.
+  # may be able to memoize this
+  def providers
+    providers = YARD::Registry.all("puppet_providers_#{name}".intern)
+    return providers if providers.empty?
+
+    providers.first.children
+  end
+
   # Converts the code object to a hash representation.
   # @return [Hash] Returns a hash representation of the code object.
   def to_hash
     hash = {}
+
     hash[:name] = name
     hash[:file] = file
     hash[:line] = line
-    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
-    hash[:properties] = properties.map(&:to_hash) if properties && !properties.empty?
-    hash[:parameters] = parameters.map(&:to_hash) if parameters && !parameters.empty?
-    hash[:features] = features.map(&:to_hash) if features && !features.empty?
+
+    hash[:docstring]  = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
+    hash[:properties] = properties.sort_by { |p| p.name }.map(&:to_hash) if properties && !properties.empty?
+    hash[:parameters] = parameters.sort_by { |p| p.name }.map(&:to_hash) if parameters && !parameters.empty?
+    hash[:checks]     = checks.sort_by { |c| c.name }.map(&:to_hash) if checks && !checks.empty?
+    hash[:features]   = features.sort_by { |f| f.name }.map(&:to_hash) if features && !features.empty?
+    hash[:providers]  = providers.sort_by { |p| p.name }.map(&:to_hash) if providers && !providers.empty?
+
     hash
   end
 end