From 187dec9ceecd64113868f2459e15eb3879c7c9f5 Mon Sep 17 00:00:00 2001
From: Peter Huene <peter@segfault.guru>
Date: Sun, 11 Sep 2016 11:27:26 -0700
Subject: [PATCH] (PDOC-63) Implement a Puppet defined type YARD handler.

This commit implements a YARD handler for Puppet defined types and the
associated code object and templates.
---
 lib/puppet-strings/yard.rb                    |  5 +++
 lib/puppet-strings/yard/code_objects.rb       |  1 +
 .../yard/code_objects/defined_type.rb         | 44 +++++++++++++++++++
 lib/puppet-strings/yard/handlers.rb           |  1 +
 .../handlers/puppet/defined_type_handler.rb   | 23 ++++++++++
 .../html/full_list_puppet_defined_type.erb    |  9 ++++
 .../templates/default/fulldoc/html/setup.rb   |  9 ++++
 .../templates/default/layout/html/setup.rb    | 19 +++++++-
 .../puppet_defined_type/html/box_info.erb     | 10 +++++
 .../puppet_defined_type/html/header.erb       |  1 +
 .../puppet_defined_type/html/overview.erb     |  6 +++
 .../default/puppet_defined_type/html/setup.rb |  5 +++
 .../puppet_defined_type/html/source.erb       | 12 +++++
 .../yard/templates/default/tags/setup.rb      |  4 +-
 14 files changed, 146 insertions(+), 3 deletions(-)
 create mode 100644 lib/puppet-strings/yard/code_objects/defined_type.rb
 create mode 100644 lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb
 create mode 100644 lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_defined_type.erb
 create mode 100644 lib/puppet-strings/yard/templates/default/puppet_defined_type/html/box_info.erb
 create mode 100644 lib/puppet-strings/yard/templates/default/puppet_defined_type/html/header.erb
 create mode 100644 lib/puppet-strings/yard/templates/default/puppet_defined_type/html/overview.erb
 create mode 100644 lib/puppet-strings/yard/templates/default/puppet_defined_type/html/setup.rb
 create mode 100644 lib/puppet-strings/yard/templates/default/puppet_defined_type/html/source.erb

diff --git a/lib/puppet-strings/yard.rb b/lib/puppet-strings/yard.rb
index 2a03364..9fa71c0 100644
--- a/lib/puppet-strings/yard.rb
+++ b/lib/puppet-strings/yard.rb
@@ -30,6 +30,7 @@ class YARD::CLI::Yardoc
       :module,
       :class,
       :puppet_class,
+      :puppet_defined_type,
     )
   end
 end
@@ -42,6 +43,10 @@ class YARD::CLI::Stats
     output 'Puppet Classes', *type_statistics_all(:puppet_class)
   end
 
+  def stats_for_puppet_defined_types
+    output 'Puppet Defined Types', *type_statistics_all(:puppet_defined_type)
+  end
+
   def output(name, data, undoc = nil)
     # Monkey patch output to accommodate our larger header widths
     @total += data if data.is_a?(Integer) && undoc
diff --git a/lib/puppet-strings/yard/code_objects.rb b/lib/puppet-strings/yard/code_objects.rb
index 93a5a0f..da6af39 100644
--- a/lib/puppet-strings/yard/code_objects.rb
+++ b/lib/puppet-strings/yard/code_objects.rb
@@ -1,4 +1,5 @@
 # The module for custom YARD code objects.
 module PuppetStrings::Yard::CodeObjects
   require 'puppet-strings/yard/code_objects/class'
+  require 'puppet-strings/yard/code_objects/defined_type'
 end
diff --git a/lib/puppet-strings/yard/code_objects/defined_type.rb b/lib/puppet-strings/yard/code_objects/defined_type.rb
new file mode 100644
index 0000000..12d4afb
--- /dev/null
+++ b/lib/puppet-strings/yard/code_objects/defined_type.rb
@@ -0,0 +1,44 @@
+require 'puppet-strings/yard/code_objects/group'
+
+# Implements the group for Puppet defined types.
+class PuppetStrings::Yard::CodeObjects::DefinedTypes < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_defined_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)
+    'Defined Types'
+  end
+end
+
+# Implements the Puppet defined type code object.
+class PuppetStrings::Yard::CodeObjects::DefinedType < PuppetStrings::Yard::CodeObjects::Base
+  attr_reader :statement
+  attr_reader :parameters
+
+  # Initializes a Puppet defined type code object.
+  # @param [PuppetStrings::Parsers::DefinedTypeStatement] statement The defined type statement that was parsed.
+  # @return [void]
+  def initialize(statement)
+    @statement = statement
+    @parameters = statement.parameters.map { |p| [p.name, p.value] }
+    super(PuppetStrings::Yard::CodeObjects::DefinedTypes.instance, statement.name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_defined_type
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    @statement.source
+  end
+end
diff --git a/lib/puppet-strings/yard/handlers.rb b/lib/puppet-strings/yard/handlers.rb
index df90be1..9eadc55 100644
--- a/lib/puppet-strings/yard/handlers.rb
+++ b/lib/puppet-strings/yard/handlers.rb
@@ -3,5 +3,6 @@ module PuppetStrings::Yard::Handlers
   # The module for custom Puppet YARD handlers.
   module Puppet
     require 'puppet-strings/yard/handlers/puppet/class_handler'
+    require 'puppet-strings/yard/handlers/puppet/defined_type_handler'
   end
 end
diff --git a/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb b/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb
new file mode 100644
index 0000000..4786c24
--- /dev/null
+++ b/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb
@@ -0,0 +1,23 @@
+require 'puppet-strings/yard/handlers/puppet/base'
+require 'puppet-strings/yard/parsers'
+require 'puppet-strings/yard/code_objects'
+
+# Implements the handler for Puppet defined types.
+class PuppetStrings::Yard::Handlers::Puppet::DefinedTypeHandler < PuppetStrings::Yard::Handlers::Puppet::Base
+  handles PuppetStrings::Yard::Parsers::Puppet::DefinedTypeStatement
+
+  process do
+    # Register the object
+    object = PuppetStrings::Yard::CodeObjects::DefinedType.new(statement)
+    register object
+
+    # Log a warning if missing documentation
+    log.warn "Missing documentation for Puppet defined type '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty?
+
+    # Set the parameter types
+    set_parameter_types(object)
+
+    # Mark the defined type as public if it doesn't already have an api tag
+    object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
+  end
+end
diff --git a/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_defined_type.erb b/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_defined_type.erb
new file mode 100644
index 0000000..095188f
--- /dev/null
+++ b/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_defined_type.erb
@@ -0,0 +1,9 @@
+<% even = false  %>
+<% @items.each do |item| %>
+    <li id="object_<%=item.path%>" class="<%= even ? 'even' : 'odd' %>">
+      <div class="item">
+        <%= linkify item, h(item.name(true)) %>
+      </div>
+    </li>
+    <% even = !even %>
+<% end %>
diff --git a/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb b/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb
index 0c58c0f..70f4b3f 100644
--- a/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb
+++ b/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 defined type list.
+# @return [void]
+def generate_puppet_defined_type_list
+  @items = Registry.all(:puppet_defined_type).sort_by {|dt| dt.name.to_s }
+  @list_title = 'Defined Type List'
+  @list_type = 'puppet_defined_type'
+  generate_list_contents
+end
+
 # Generates the searchable Ruby method list.
 # @return [void]
 def generate_method_list
diff --git a/lib/puppet-strings/yard/templates/default/layout/html/setup.rb b/lib/puppet-strings/yard/templates/default/layout/html/setup.rb
index bd5a48e..656e655 100644
--- a/lib/puppet-strings/yard/templates/default/layout/html/setup.rb
+++ b/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, :files, :objects]]]
+    sections :layout, [:index, [:listing, [:classes, :defined_types, :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::DefinedType
+    @nav_url = url_for_list('puppet_defined_type')
+    @page_title = "Defined Type: #{object.name}"
+    @path = object.path
   else
     @path = object.path
   end
@@ -46,6 +50,11 @@ def create_menu_lists
       title: 'Puppet Classes',
       search_title: 'Puppet Classes'
     },
+    {
+      type: 'puppet_defined_type',
+      title: 'Defined Types',
+      search_title: 'Defined Types',
+    },
     {
       type: 'class',
       title: 'Ruby Classes',
@@ -95,6 +104,14 @@ def classes
   erb(:objects)
 end
 
+# Renders the defined types section.
+# @return [String] Returns the rendered section.
+def defined_types
+  @title = 'Defined Type Listing A-Z'
+  @objects_by_letter = objects_by_letter(:puppet_defined_type)
+  erb(:objects)
+end
+
 # Renders the objects section.
 # @return [String] Returns the rendered section.
 def objects
diff --git a/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/box_info.erb b/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/box_info.erb
new file mode 100644
index 0000000..49a6460
--- /dev/null
+++ b/lib/puppet-strings/yard/templates/default/puppet_defined_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>
diff --git a/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/header.erb b/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/header.erb
new file mode 100644
index 0000000..91f06e7
--- /dev/null
+++ b/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/header.erb
@@ -0,0 +1 @@
+<h1>Defined Type: <%= object.name %></h1>
diff --git a/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/overview.erb b/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/overview.erb
new file mode 100644
index 0000000..a5b527a
--- /dev/null
+++ b/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/overview.erb
@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>
diff --git a/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/setup.rb b/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/setup.rb
new file mode 100644
index 0000000..d8858fb
--- /dev/null
+++ b/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/setup.rb
@@ -0,0 +1,5 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :overview, T('tags'), :source
+end
diff --git a/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/source.erb b/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/source.erb
new file mode 100644
index 0000000..0fd3c5e
--- /dev/null
+++ b/lib/puppet-strings/yard/templates/default/puppet_defined_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>
diff --git a/lib/puppet-strings/yard/templates/default/tags/setup.rb b/lib/puppet-strings/yard/templates/default/tags/setup.rb
index be92cf0..2166fdf 100644
--- a/lib/puppet-strings/yard/templates/default/tags/setup.rb
+++ b/lib/puppet-strings/yard/templates/default/tags/setup.rb
@@ -3,6 +3,6 @@
 def param
   tag(:param) if
     object.type == :method ||
-    object.type == :puppet_class
+    object.type == :puppet_class ||
+    object.type == :puppet_defined_type
 end
-