puppet-strings 2.3.0 → 2.7.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.

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.3.0'.freeze
+  VERSION = '2.7.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
@@ -96,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