puppet-strings 2.5.0 → 2.9.0

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

@@ -1,4 +1,4 @@
-### `<%= name %>`
+### <a name="<%= link %>"></a>`<%= name %>`
 
 <% if text -%>
 <%= text %>
@@ -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(', ') -%>`

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

@@ -1,4 +1,4 @@
-### `<%= name %>`
+### <a name="<%= link %>"></a>`<%= name %>`
 
 <% if text -%>
 <%= text %>
@@ -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] %>)
+<% end -%>
 
 <% params.each do |param| -%>
-##### `<%= param[:name] %>`
+##### <a name="<%= param[:name] %>"></a>`<%= param[:name] %>`
 
 <% if param[:types] -%>
 Data type: `<%= param[:types].join(', ') -%>`

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

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

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

@@ -1,4 +1,4 @@
-### `<%= name %>`
+### <a name="<%= link %>"></a>`<%= name %>`
 
 Type: <%= type %>
 

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 %>
@@ -98,7 +98,11 @@ 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('`, `') %>`
@@ -116,7 +120,9 @@ Aliases: `<%= param[:aliases].to_s.delete('{').delete('}') %>`
 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 -%>
+<% if param[:description] -%>
 <%= word_wrap(param[:description]) %>
+<% end -%>
 
 <% if options_for_param(param[:name]) -%>
 Options:

data/lib/puppet-strings/markdown.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/json'
 
 # module for parsing Yard Registries and generating markdown
@@ -15,15 +17,15 @@ module PuppetStrings::Markdown
   # @return [String] markdown doc
   def self.generate
     final = "# Reference\n\n"
-    final << "<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n"
-    final << PuppetStrings::Markdown::TableOfContents.render
-    final << PuppetStrings::Markdown::PuppetClasses.render
-    final << PuppetStrings::Markdown::DefinedTypes.render
-    final << PuppetStrings::Markdown::ResourceTypes.render
-    final << PuppetStrings::Markdown::Functions.render
-    final << PuppetStrings::Markdown::DataTypes.render
-    final << PuppetStrings::Markdown::PuppetTasks.render
-    final << PuppetStrings::Markdown::PuppetPlans.render
+    final += "<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n"
+    final += PuppetStrings::Markdown::TableOfContents.render
+    final += PuppetStrings::Markdown::PuppetClasses.render
+    final += PuppetStrings::Markdown::DefinedTypes.render
+    final += PuppetStrings::Markdown::ResourceTypes.render
+    final += PuppetStrings::Markdown::Functions.render
+    final += PuppetStrings::Markdown::DataTypes.render
+    final += PuppetStrings::Markdown::PuppetTasks.render
+    final += PuppetStrings::Markdown::PuppetPlans.render
 
     final
   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/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/tasks/validate.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'puppet-strings'
+require 'tempfile'
+
+namespace :strings do
+  namespace :validate do
+    desc 'Validate the reference is up to date'
+    task :reference, [:patterns, :debug, :backtrace] do |t, args|
+      filename = 'REFERENCE.md'
+
+      unless File.exist?(filename)
+        STDERR.puts "#{filename} does not exist"
+        exit 1
+      end
+
+      patterns = args[:patterns]
+      patterns = patterns.split if patterns
+      patterns ||= PuppetStrings::DEFAULT_SEARCH_PATTERNS
+
+      generated = Tempfile.create do |file|
+        options = {
+          debug: args[:debug] == 'true',
+          backtrace: args[:backtrace] == 'true',
+          json: false,
+          markdown: true,
+          path: file,
+        }
+        PuppetStrings.generate(patterns, options)
+
+        file.read
+      end
+
+      existing = File.read(filename)
+
+      if generated != existing
+        STDERR.puts "#{filename} is outdated"
+        exit 1
+      end
+    end
+  end
+end

data/lib/puppet-strings/tasks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rake'
 require 'rake/tasklib'
 
@@ -6,5 +8,6 @@ module PuppetStrings
   module Tasks
     require 'puppet-strings/tasks/generate.rb'
     require 'puppet-strings/tasks/gh_pages.rb'
+    require 'puppet-strings/tasks/validate.rb'
   end
 end

data/lib/puppet-strings/version.rb

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

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'
 
@@ -86,8 +88,8 @@ class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObje
     hash[:file] = file
     hash[:line] = line
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring, %i[param option enum return example])
-    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[:functions] = functions.map do |func|
       {
         name: func.name,

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'
 
@@ -146,11 +148,12 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
   end
 
   def parameters
+    @parameters ||= []  # guard against not filled 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' }
+    return @parameters if @parameters&.any? { |p| p.name == 'provider' }
 
     provider_param = Parameter.new(
       'provider',
@@ -158,6 +161,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
       "to specify this --- Puppet will usually discover the appropriate provider for your platform."
     )
 
+    @parameters ||= []
     @parameters << provider_param
   end
 
@@ -167,6 +171,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
   def providers
     providers = YARD::Registry.all("puppet_providers_#{name}".intern)
     return providers if providers.empty?
+
     providers.first.children
   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/handlers/helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PuppetStrings::Yard::Handlers::Helpers
   # Logs a warning if a summary tag has more than 140 characters
   def self.validate_summary_tag(object)

data/lib/puppet-strings/yard/handlers/json/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class PuppetStrings::Yard::Handlers::JSON::Base < YARD::Handlers::Base
   def self.handles?(statement)
     handlers.any? {|handler| statement.is_a?(handler)}

data/lib/puppet-strings/yard/handlers/json/task_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/json/base'
 require 'puppet-strings/yard/parsers'
 require 'puppet-strings/yard/parsers/json/parser'

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Implements the base handler for Puppet language handlers.
 class PuppetStrings::Yard::Handlers::Puppet::Base < YARD::Handlers::Base
   # Determine sif the handler handles the given statement.
@@ -17,6 +19,7 @@ class PuppetStrings::Yard::Handlers::Puppet::Base < YARD::Handlers::Base
     tags = object.tags(:param)
     tags.each do |tag|
       next if statement.parameters.find { |p| tag.name == p.name }
+
       log.warn "The @param tag for parameter '#{tag.name}' has no matching parameter at #{statement.file}:#{statement.line}." unless tag.name == 'name' || tag.name == 'title'
     end
 

data/lib/puppet-strings/yard/handlers/puppet/class_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/puppet/base'
 require 'puppet-strings/yard/parsers'

data/lib/puppet-strings/yard/handlers/puppet/data_type_alias_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/puppet/base'
 require 'puppet-strings/yard/parsers'

data/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/puppet/base'
 require 'puppet-strings/yard/parsers'

data/lib/puppet-strings/yard/handlers/puppet/function_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/puppet/base'
 require 'puppet-strings/yard/parsers'
@@ -37,7 +39,7 @@ class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Ya
   def add_return_tag(object, type=nil)
     tag = object.tag(:return)
     if tag
-      if (type && tag.types.first) && (type != tag.types.first)
+      if (type && tag.types && tag.types.first) && (type != tag.types.first)
         log.warn "Documented return type does not match return type in function definition near #{statement.file}:#{statement.line}."
       end
 

data/lib/puppet-strings/yard/handlers/puppet/plan_handler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/puppet/base'
 require 'puppet-strings/yard/parsers'

data/lib/puppet-strings/yard/handlers/ruby/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'ripper'
 
 # Implements the base handler for Ruby language handlers.
@@ -12,6 +14,7 @@ class PuppetStrings::Yard::Handlers::Ruby::Base < YARD::Handlers::Ruby::Base
   # @return [String] Returns a string representation of the node or nil if a string representation was not possible.
   def node_as_string(node)
     return nil unless node
+
     case node.type
     when :symbol, :symbol_literal
       node.source[1..-1]
@@ -42,8 +45,10 @@ class PuppetStrings::Yard::Handlers::Ruby::Base < YARD::Handlers::Ruby::Base
   def get_name(statementobject, statementtype)
     parameters = statementobject.parameters(false)
     raise YARD::Parser::UndocumentableError, "Expected at least one parameter to #{statementtype} at #{statementobject.file}:#{statementobject.line}." if parameters.empty?
+
     name = node_as_string(parameters.first)
     raise YARD::Parser::UndocumentableError, "Expected a symbol or string literal for first parameter but found '#{parameters.first.type}' at #{statement.file}:#{statement.line}." unless name
+
     name
   end
 end