puppet-strings 2.2.0 → 2.6.0

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

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
 # The module for custom YARD tags.
 module PuppetStrings::Yard::Tags
+  require 'puppet-strings/yard/tags/factory'
   require 'puppet-strings/yard/tags/parameter_directive'
   require 'puppet-strings/yard/tags/property_directive'
   require 'puppet-strings/yard/tags/overload_tag'
   require 'puppet-strings/yard/tags/summary_tag'
+  require 'puppet-strings/yard/tags/enum_tag'
 end

data/lib/puppet-strings/yard/tags/enum_tag.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'yard/tags/option_tag'
+
+# Implements an enum tag for describing enumerated value data types
+
+class PuppetStrings::Yard::Tags::EnumTag < YARD::Tags::OptionTag
+  # Registers the tag with YARD.
+  # @return [void]
+  def self.register!
+    YARD::Tags::Library.define_tag("puppet.enum", :enum, :with_enums)
+    YARD::Tags::Library.visible_tags.place(:enum).after(:option)
+  end
+end

data/lib/puppet-strings/yard/tags/factory.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'yard/tags/default_factory'
+require 'puppet-strings/yard/tags/enum_tag'
+
+class PuppetStrings::Yard::Tags::Factory < YARD::Tags::DefaultFactory
+
+  # Parses tag text and creates a new enum tag type. Modeled after
+  # the parse_tag_with_options method in YARD::Tags::DefaultFactory.
+  #
+  # @param tag_name        the name of the tag to parse
+  # @param [String] text   the raw tag text
+  # @return [Tag]          a tag object with the tag_name, name, and nested Tag as type
+  def parse_tag_with_enums(tag_name, text)
+    name, text = *extract_name_from_text(text)
+    PuppetStrings::Yard::Tags::EnumTag.new(tag_name, name, parse_tag_with_name(tag_name, text))
+  end
+end

data/lib/puppet-strings/yard/tags/overload_tag.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Implements an overload tag for Puppet functions
 #
 # This differs from Yard's overload tag in that the signatures are formatted according to Puppet language rules.
@@ -22,7 +24,7 @@ class PuppetStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag
     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
@@ -75,6 +77,7 @@ class PuppetStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag
   # @return Returns what the method call on the object would return.
   def method_missing(method_name, *args, &block)
     return object.send(method_name, *args, &block) if object.respond_to? method_name
+
     super
   end
 
@@ -100,7 +103,7 @@ class PuppetStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag
     hash[:text] = text if text
     hash[:signature] = signature
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring) if !docstring.blank?
-    defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
+    defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
     hash[:defaults] = defaults unless defaults.empty?
     hash[:types] = types if types
     hash[:name] = name if name

data/lib/puppet-strings/yard/tags/parameter_directive.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects'
 
 # Implements a parameter directive (e.g. #@!puppet.type.param) for documenting Puppet resource types.
@@ -5,14 +7,13 @@ class PuppetStrings::Yard::Tags::ParameterDirective < YARD::Tags::Directive
   # Called to invoke the directive.
   # @return [void]
   def call
-    return unless object && object.respond_to?(:add_parameter)
+    return unless object&.respond_to?(:add_parameter)
+
     # Add a parameter to the resource
     parameter = PuppetStrings::Yard::CodeObjects::Type::Parameter.new(tag.name, tag.text)
-    if tag.types
-      tag.types.each do |value|
+    tag.types&.each do |value|
         parameter.add(value)
       end
-    end
     object.add_parameter parameter
   end
 

data/lib/puppet-strings/yard/tags/property_directive.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/yard/code_objects'
 
 # Implements a parameter directive (e.g. #@!puppet.type.property) for documenting Puppet resource types.
@@ -5,14 +7,13 @@ class PuppetStrings::Yard::Tags::PropertyDirective < YARD::Tags::Directive
   # Called to invoke the directive.
   # @return [void]
   def call
-    return unless object && object.respond_to?(:add_property)
+    return unless object&.respond_to?(:add_property)
+
     # Add a property to the resource
     property = PuppetStrings::Yard::CodeObjects::Type::Property.new(tag.name, tag.text)
-    if tag.types
-      tag.types.each do |value|
+    tag.types&.each do |value|
         property.add(value)
       end
-    end
     object.add_property property
   end
 

data/lib/puppet-strings/yard/tags/summary_tag.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Implements a summary tag for general purpose short descriptions
 
 class PuppetStrings::Yard::Tags::SummaryTag < YARD::Tags::Tag

data/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_data_type.erb

@@ -0,0 +1,10 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(false)) %>
+        <% if item.type == :puppet_data_type_alias %><small>Alias</small><% end %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb

@@ -7,6 +7,15 @@ def generate_puppet_class_list
   generate_list_contents
 end
 
+# Generates the searchable Puppet data type list.
+# @return [void]
+def generate_puppet_data_type_list
+  @items = Registry.all(:puppet_data_type, :puppet_data_type_alias).sort_by {|dt| dt.name.to_s }
+  @list_title = 'Data Type List'
+  @list_type = 'puppet_data_type'
+  generate_list_contents
+end
+
 # Generates the searchable Puppet defined type list.
 # @return [void]
 def generate_puppet_defined_type_list

data/lib/puppet-strings/yard/templates/default/layout/html/objects.erb

@@ -23,6 +23,8 @@
               <small>(Resource type: <%= obj.type_name %>)</small>
       <% elsif obj.type == :puppet_function %>
               <small>(<%= obj.function_type %>)</small>
+      <% elsif obj.type == :puppet_data_type_alias %>
+              <small>(Alias)</small>
       <% end %>
             </li>
     <% end %>

data/lib/puppet-strings/yard/templates/default/layout/html/setup.rb

@@ -4,7 +4,7 @@ def init
   case object
   when '_index.html'
     @page_title = options.title
-    sections :layout, [:index, [:listing, [:classes, :defined_types, :types, :providers, :functions, :tasks, :plans, :files, :objects]]]
+    sections :layout, [:index, [:listing, [:classes, :data_types, :defined_types, :types, :providers, :functions, :tasks, :plans, :files, :objects]]]
   else
     super
   end
@@ -30,6 +30,10 @@ def layout
     @nav_url = url_for_list('puppet_class')
     @page_title = "Puppet Class: #{object.name}"
     @path = object.path
+  when PuppetStrings::Yard::CodeObjects::DataType, PuppetStrings::Yard::CodeObjects::DataTypeAlias
+    @nav_url = url_for_list('puppet_data_type')
+    @page_title = "Data Type: #{object.name}"
+    @path = object.path
   when PuppetStrings::Yard::CodeObjects::DefinedType
     @nav_url = url_for_list('puppet_defined_type')
     @page_title = "Defined Type: #{object.name}"
@@ -76,6 +80,11 @@ def create_menu_lists
       title: 'Puppet Classes',
       search_title: 'Puppet Classes'
     },
+    {
+      type: 'puppet_data_type',
+      title: 'Data Types',
+      search_title: 'Data Types',
+    },
     {
       type: 'puppet_defined_type',
       title: 'Defined Types',
@@ -155,6 +164,14 @@ def classes
   erb(:objects)
 end
 
+# Renders the data types section.
+# @return [String] Returns the rendered section.
+def data_types
+  @title = 'Data Type Listing A-Z'
+  @objects_by_letter = objects_by_letter(:puppet_data_type, :puppet_data_type_alias)
+  erb(:objects)
+end
+
 # Renders the defined types section.
 # @return [String] Returns the rendered section.
 def defined_types

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/box_info.erb

@@ -0,0 +1,10 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+      <% end %>
+    </dd>
+  </dl>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/header.erb

@@ -0,0 +1 @@
+<h1>Puppet Data Type: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/method_details_list.erb

@@ -0,0 +1,6 @@
+<h2>Data Type Functions</h2>
+<% method_listing.each_with_index do |meth, i| %>
+  <div id="<%= meth.name %>-instance_method"><h3><%= meth.name %></h3>
+  <%= yieldall :object => meth, :owner => object, :index => i %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/note.erb

@@ -0,0 +1,6 @@
+<% object.tags(:note).each do |tag| %>
+  <div class="note notetag">
+    <strong>Note:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/setup.rb

@@ -0,0 +1,13 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :summary, :overview, :note, :todo, T('tags'), :method_details_list, [T('method_details')], :source
+end
+
+def method_listing
+  sort_listing(object.functions)
+end
+
+def sort_listing(list)
+  list.sort_by {|o| [o.scope.to_s, o.name.to_s.downcase] }
+end

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/source.erb

@@ -0,0 +1,12 @@
+<div class="method_details_list">
+  <table class="source_code">
+    <tr>
+      <td>
+        <pre class="lines"><%= "\n\n\n" %><%= h format_lines(object) %></pre>
+      </td>
+      <td>
+        <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span><%= "\n\n" %><%= html_syntax_highlight object.source %></pre>
+      </td>
+    </tr>
+  </table>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/summary.erb

@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/todo.erb

@@ -0,0 +1,6 @@
+<% object.tags(:todo).each do |tag| %>
+  <div class="note todo">
+    <strong>TODO:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/alias_of.erb

@@ -0,0 +1,10 @@
+<% if @alias_of && !@alias_of.empty? %>
+<div class="tags">
+  <p class="tag_title"><%= @tag_title %></p>
+  <div class="docstring">
+    <div class="discussion">
+      <pre class="code"><span class="info"><%= @alias_of %></span></pre>
+    </div>
+  </div>
+</div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/box_info.erb

@@ -0,0 +1,10 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+      <% end %>
+    </dd>
+  </dl>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/header.erb

@@ -0,0 +1 @@
+<h1>Puppet Data Type Alias: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/note.erb

@@ -0,0 +1,6 @@
+<% object.tags(:note).each do |tag| %>
+  <div class="note notetag">
+    <strong>Note:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/setup.rb

@@ -0,0 +1,17 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :summary, :overview, :alias_of, :note, :todo, T('tags'), :source
+end
+
+# Renders the alias_of section.
+# @return [String] Returns the rendered section.
+def alias_of
+  # Properties are the same thing as parameters (from the documentation standpoint),
+  # so reuse the same template but with a different title and data source.
+  #@parameters = object.properties || []
+  #@parameters.sort_by! { |p| p.name }
+  @tag_title = 'Alias of'
+  @alias_of = object.alias_of
+  erb(:alias_of)
+end

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/source.erb

@@ -0,0 +1,12 @@
+<div class="method_details_list">
+  <table class="source_code">
+    <tr>
+      <td>
+        <pre class="lines"><%= "\n\n\n" %><%= h format_lines(object) %></pre>
+      </td>
+      <td>
+        <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span><%= "\n\n" %><%= html_syntax_highlight object.source %></pre>
+      </td>
+    </tr>
+  </table>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/summary.erb

@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/todo.erb

@@ -0,0 +1,6 @@
+<% object.tags(:todo).each do |tag| %>
+  <div class="note todo">
+    <strong>TODO:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_function/html/setup.rb

@@ -1,5 +1,5 @@
 # Initializes the template.
 # @return [void]
 def init
-  sections :header, :box_info, :summary, :overview, :note, :todo, [T('tags'), :source]
+  sections :header, :box_info, :summary, :overview, [:note, :todo, T('tags'), :source]
 end

data/lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb

@@ -16,7 +16,9 @@ end
 def properties
   # Properties are the same thing as parameters (from the documentation standpoint),
   # so reuse the same template but with a different title and data source.
-  @parameters = object.properties || []
+  #
+  # "checks" such as "creates" and "onlyif" are another type of property
+  @parameters = (object.properties || []) + (object.checks || [])
   @parameters.sort_by! { |p| p.name }
   @tag_title = 'Properties'
   erb(:parameters)

data/lib/puppet-strings/yard/templates/default/tags/html/enum.erb

@@ -0,0 +1,17 @@
+<% if object.has_tag?(:enum) %>
+  <% object.parameters.each do |param, default| %>
+    <% tags = object.tags(:enum).select {|x| x.name.to_s == param.to_s.sub(/^\*+|:$/, '') } %>
+    <% next if tags.empty? %>
+    <p class="tag_title">Enum Options (<tt><%= param %></tt>):</p>
+    <ul class="option">
+      <% for tag in tags %>
+        <li>
+          <span class="name"><%= tag.pair.name %></span>
+          <% if tag.pair.text && tag.pair.text =~ /\S/ %>
+            &mdash; <%= htmlify_line(tag.pair.text) %>
+          <% end %>
+        </li>
+      <% end %>
+    </ul>
+  <% end %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/tags/setup.rb

@@ -4,6 +4,7 @@ def param
   tag(:param) if
     object.type == :method ||
     object.type == :puppet_class ||
+    object.type == :puppet_data_type ||
     object.type == :puppet_defined_type ||
     object.type == :puppet_function ||
     object.type == :puppet_task ||
@@ -15,3 +16,9 @@ end
 def overload
   erb(if object.type == :puppet_function then :puppet_overload else :overload end)
 end
+
+# Renders the enum section.
+# @return [String] Returns the rendered section.
+def enum
+  erb(:enum)
+end