puppet-strings 2.2.0 → 2.6.0

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

@@ -0,0 +1,67 @@
+### <a name="<%= link %>"></a>`<%= name %>`
+
+#### `<%= signature %>`
+
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} function." %>
+
+<% end -%>
+<% if note -%>
+* **Note** <%= note %>
+
+<% end -%>
+<% if return_type -%>
+Returns: `<%= return_type %>`<% if return_val %> <%= return_val %><% end %>
+
+<% end -%>
+<% if raises -%>
+Raises:
+<% raises.each do |r| -%>
+* <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
+<% end -%>
+
+<% end -%>
+<% if examples -%>
+##### Examples
+
+<% examples.each do |eg| -%>
+###### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
+<% end -%>
+<% if params -%>
+<% params.each do |param| -%>
+##### `<%= param[:name]  %>`
+
+Data type: `<%= param[:types][0] %>`
+
+<%= param[:text] %>
+
+<% if options_for_param(param[:name]) -%>
+Options:
+
+<% options_for_param(param[:name]).each do |o| -%>
+* **<%= 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 -%>
+<% end -%>
+<% end -%>

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

@@ -1,4 +1,4 @@
-### <%= name %>
+### <a name="<%= link %>"></a>`<%= name %>`
 
 Type: <%= type %>
 
@@ -55,6 +55,7 @@ Returns: `<%= sig.return_type %>`<% if sig.return_val %> <%= sig.return_val %><%
 <% end -%>
 <% if raises -%>
 Raises:
+
 <% raises.each do |r| -%>
 * <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
 <% end -%>
@@ -87,6 +88,14 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if sig.enums_for_param(param[:name]) -%>
+Options:
+
+<% sig.enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% end -%>
 <% end -%>

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] -%>
@@ -77,9 +77,17 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if enums_for_param(prop[:name]) -%>
+Options:
+
+<% enums_for_param(prop[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% if prop[:default] -%>
-Default value: <%= prop[:default] %>
+Default value: `<%= prop[:default] %>`
 
 <% end -%>
 <% end -%>
@@ -90,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] -%>
@@ -101,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:
@@ -117,9 +131,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 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.
@@ -33,11 +35,12 @@ namespace :strings do
         end
       end
     end
+    # rubocop:enable Style/PreferredHashMethods
 
-    [:json,:markdown].each { |format| parse_format_option(args, options, format) }
+    %i[json markdown].each { |format| parse_format_option(args, options, format) }
 
     warn('yard_args behavior is a little dodgy, use at your own risk') if args[:yard_args]
-    options[:yard_args] = args[:yard_args].split if args.has_key? :yard_args
+    options[:yard_args] = args[:yard_args].split if args.key? :yard_args
 
     PuppetStrings.generate(patterns, options)
   end

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.2.0'.freeze
+  VERSION = '2.6.0'
 end

data/lib/puppet-strings/yard.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'yard'
 
 # Module for YARD related functionality.
@@ -11,6 +13,9 @@ module PuppetStrings::Yard
   # Sets up YARD for use with puppet-strings.
   # @return [void]
   def self.setup!
+    # Register our factory
+    YARD::Tags::Library.default_factory = PuppetStrings::Yard::Tags::Factory
+
     # Register the template path
     YARD::Templates::Engine.register_template_path(File.join(File.dirname(__FILE__), 'yard', 'templates'))
 
@@ -30,6 +35,9 @@ module PuppetStrings::Yard
     # Register the summary tag
     PuppetStrings::Yard::Tags::SummaryTag.register!
 
+    # Register the enum tag
+    PuppetStrings::Yard::Tags::EnumTag.register!
+
     # Ignore documentation on Puppet DSL calls
     # This prevents the YARD DSL parser from emitting warnings for Puppet's Ruby DSL
     YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS['create_function'] = true
@@ -46,6 +54,8 @@ class YARD::CLI::Yardoc
       :module,
       :class,
       :puppet_class,
+      :puppet_data_type,
+      :puppet_data_type_alias,
       :puppet_defined_type,
       :puppet_type,
       :puppet_provider,
@@ -64,6 +74,14 @@ class YARD::CLI::Stats
     output 'Puppet Classes', *type_statistics_all(:puppet_class)
   end
 
+  def stats_for_puppet_data_types
+    output 'Puppet Data Types', *type_statistics_all(:puppet_data_type)
+  end
+
+  def stats_for_puppet_data_type_aliases
+    output 'Puppet Data Type Aliases', *type_statistics_all(:puppet_data_type_alias)
+  end
+
   def stats_for_puppet_defined_types
     output 'Puppet Defined Types', *type_statistics_all(:puppet_defined_type)
   end
@@ -86,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,6 +1,10 @@
+# frozen_string_literal: true
+
 # The module for custom YARD code objects.
 module PuppetStrings::Yard::CodeObjects
   require 'puppet-strings/yard/code_objects/class'
+  require 'puppet-strings/yard/code_objects/data_type'
+  require 'puppet-strings/yard/code_objects/data_type_alias'
   require 'puppet-strings/yard/code_objects/defined_type'
   require 'puppet-strings/yard/code_objects/type'
   require 'puppet-strings/yard/code_objects/provider'

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.
@@ -51,9 +53,9 @@ class PuppetStrings::Yard::CodeObjects::Class < PuppetStrings::Yard::CodeObjects
     hash[:line] = line
     hash[:inherits] = statement.parent_class if statement.parent_class
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
-    defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
-    hash[:defaults] = defaults unless defaults.empty?
-    hash[:source] = source unless source && source.empty?
+    defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
+    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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'puppet-strings/yard/code_objects/group'
+require 'puppet-strings/yard/util'
+
+# Implements the group for Puppet DataTypes.
+class PuppetStrings::Yard::CodeObjects::DataTypes < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_data_types)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Puppet Data Types'
+  end
+end
+
+# Implements the Puppet DataType code object.
+class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObjects::Base
+  # Initializes a Puppet class code object.
+  # @param [String] The name of the Data Type
+  # @return [void]
+  def initialize(name)
+    super(PuppetStrings::Yard::CodeObjects::DataTypes.instance, name)
+    @defaults = {}
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_data_type
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    # Not implemented, but would be nice!
+    nil
+  end
+
+  def add_parameter(name, type, default)
+    tag = docstring.tags(:param).find { |item| item.name == name }
+    if tag.nil?
+      tag = YARD::Tags::Tag.new(:param, '', nil, name)
+      docstring.add_tag(tag)
+    end
+    type = [type] unless type.is_a?(Array)
+    tag.types = type if tag.types.nil?
+    set_parameter_default(name, default)
+  end
+
+  def set_parameter_default(param_name, default)
+    defaults.delete(param_name)
+    defaults[param_name] = default unless default.nil?
+  end
+
+  def parameters
+    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
+    hash = {}
+    hash[:name] = name
+    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.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