From 4990576f61d9edaa00720490beb6e929b86b13a4 Mon Sep 17 00:00:00 2001
From: Will Hopper <whopper@puppetlabs.com>
Date: Wed, 15 Mar 2017 16:29:01 -0700
Subject: [PATCH 1/3] (PDOC-161) Add `summary` tag for short descriptions

This tag is primarily meant to be applied to Puppet classes,
but it is also supported by every other construct that can be
documented with strings.
---
 lib/puppet-strings/yard.rb                    |  3 ++
 lib/puppet-strings/yard/handlers/helpers.rb   |  8 ++++
 .../yard/handlers/puppet/class_handler.rb     |  4 ++
 .../handlers/puppet/defined_type_handler.rb   |  4 ++
 .../yard/handlers/puppet/function_handler.rb  |  4 ++
 .../yard/handlers/ruby/function_handler.rb    |  4 ++
 .../yard/handlers/ruby/provider_handler.rb    |  4 ++
 .../yard/handlers/ruby/type_handler.rb        |  4 ++
 lib/puppet-strings/yard/tags.rb               |  1 +
 lib/puppet-strings/yard/tags/summary_tag.rb   |  9 ++++
 .../default/puppet_class/html/setup.rb        |  2 +-
 .../default/puppet_class/html/summary.erb     |  4 ++
 .../default/puppet_defined_type/html/setup.rb |  2 +-
 .../puppet_defined_type/html/summary.erb      |  4 ++
 .../default/puppet_function/html/setup.rb     |  2 +-
 .../default/puppet_function/html/summary.erb  |  4 ++
 .../default/puppet_provider/html/setup.rb     |  2 +-
 .../default/puppet_provider/html/summary.erb  |  4 ++
 .../default/puppet_type/html/setup.rb         |  2 +-
 .../default/puppet_type/html/summary.erb      |  4 ++
 .../handlers/puppet/class_handler_spec.rb     | 39 ++++++++++++++++
 .../puppet/defined_type_handler_spec.rb       | 46 +++++++++++++++++++
 .../handlers/puppet/function_handler_spec.rb  | 37 +++++++++++++++
 .../handlers/ruby/function_handler_spec.rb    | 39 ++++++++++++++++
 .../handlers/ruby/provider_handler_spec.rb    | 31 +++++++++++++
 .../yard/handlers/ruby/type_handler_spec.rb   | 31 +++++++++++++
 26 files changed, 293 insertions(+), 5 deletions(-)
 create mode 100644 lib/puppet-strings/yard/handlers/helpers.rb
 create mode 100644 lib/puppet-strings/yard/tags/summary_tag.rb
 create mode 100644 lib/puppet-strings/yard/templates/default/puppet_class/html/summary.erb
 create mode 100644 lib/puppet-strings/yard/templates/default/puppet_defined_type/html/summary.erb
 create mode 100644 lib/puppet-strings/yard/templates/default/puppet_function/html/summary.erb
 create mode 100644 lib/puppet-strings/yard/templates/default/puppet_provider/html/summary.erb
 create mode 100644 lib/puppet-strings/yard/templates/default/puppet_type/html/summary.erb

diff --git a/lib/puppet-strings/yard.rb b/lib/puppet-strings/yard.rb
index 726b062..abba601 100644
--- a/lib/puppet-strings/yard.rb
+++ b/lib/puppet-strings/yard.rb
@@ -24,6 +24,9 @@ module PuppetStrings::Yard
     PuppetStrings::Yard::Tags::ParameterDirective.register!
     PuppetStrings::Yard::Tags::PropertyDirective.register!
 
+    # Register the summary tag
+    PuppetStrings::Yard::Tags::SummaryTag.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
diff --git a/lib/puppet-strings/yard/handlers/helpers.rb b/lib/puppet-strings/yard/handlers/helpers.rb
new file mode 100644
index 0000000..38ddfa7
--- /dev/null
+++ b/lib/puppet-strings/yard/handlers/helpers.rb
@@ -0,0 +1,8 @@
+module PuppetStrings::Yard::Handlers::Helpers
+  # Logs a warning if a summary tag has more than 140 characters
+  def self.validate_summary_tag(object)
+    if object.has_tag?(:summary) && object.tag(:summary).text.length > 140
+      log.warn "The length of the summary for #{object.type} '#{object.name}' exceeds the recommended limit of 140 characters."
+    end
+  end
+end
diff --git a/lib/puppet-strings/yard/handlers/puppet/class_handler.rb b/lib/puppet-strings/yard/handlers/puppet/class_handler.rb
index 9415bc5..e026b02 100644
--- a/lib/puppet-strings/yard/handlers/puppet/class_handler.rb
+++ b/lib/puppet-strings/yard/handlers/puppet/class_handler.rb
@@ -1,3 +1,4 @@
+require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/puppet/base'
 require 'puppet-strings/yard/parsers'
 require 'puppet-strings/yard/code_objects'
@@ -19,5 +20,8 @@ class PuppetStrings::Yard::Handlers::Puppet::ClassHandler < PuppetStrings::Yard:
 
     # Mark the class 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
+
+    # Warn if a summary longer than 140 characters was provided
+    PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
   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
index 4786c24..2d03f6b 100644
--- a/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb
+++ b/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb
@@ -1,3 +1,4 @@
+require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/puppet/base'
 require 'puppet-strings/yard/parsers'
 require 'puppet-strings/yard/code_objects'
@@ -19,5 +20,8 @@ class PuppetStrings::Yard::Handlers::Puppet::DefinedTypeHandler < PuppetStrings:
 
     # 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
+
+    # Warn if a summary longer than 140 characters was provided
+    PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
   end
 end
diff --git a/lib/puppet-strings/yard/handlers/puppet/function_handler.rb b/lib/puppet-strings/yard/handlers/puppet/function_handler.rb
index 5aeaec4..579fcd4 100644
--- a/lib/puppet-strings/yard/handlers/puppet/function_handler.rb
+++ b/lib/puppet-strings/yard/handlers/puppet/function_handler.rb
@@ -1,3 +1,4 @@
+require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/puppet/base'
 require 'puppet-strings/yard/parsers'
 require 'puppet-strings/yard/code_objects'
@@ -27,6 +28,9 @@ class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Ya
 
     # Mark the class 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
+
+    # Warn if a summary longer than 140 characters was provided
+    PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
   end
 
   private
diff --git a/lib/puppet-strings/yard/handlers/ruby/function_handler.rb b/lib/puppet-strings/yard/handlers/ruby/function_handler.rb
index 858e056..2ee27fb 100644
--- a/lib/puppet-strings/yard/handlers/ruby/function_handler.rb
+++ b/lib/puppet-strings/yard/handlers/ruby/function_handler.rb
@@ -1,3 +1,4 @@
+require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/ruby/base'
 require 'puppet-strings/yard/code_objects'
 require 'puppet-strings/yard/util'
@@ -61,6 +62,9 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
 
     # Mark the function 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
+
+    # Warn if a summary longer than 140 characters was provided
+    PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
   end
 
   private
diff --git a/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb b/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb
index f3141be..e2955eb 100644
--- a/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb
+++ b/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb
@@ -1,3 +1,4 @@
+require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/ruby/base'
 require 'puppet-strings/yard/code_objects'
 require 'puppet-strings/yard/util'
@@ -34,6 +35,9 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
 
     # Mark the provider 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
+
+    # Warn if a summary longer than 140 characters was provided
+    PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
   end
 
   private
diff --git a/lib/puppet-strings/yard/handlers/ruby/type_handler.rb b/lib/puppet-strings/yard/handlers/ruby/type_handler.rb
index a616ad5..f477291 100644
--- a/lib/puppet-strings/yard/handlers/ruby/type_handler.rb
+++ b/lib/puppet-strings/yard/handlers/ruby/type_handler.rb
@@ -1,3 +1,4 @@
+require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/ruby/base'
 require 'puppet-strings/yard/code_objects'
 require 'puppet-strings/yard/util'
@@ -30,6 +31,9 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha
 
     # Mark the 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
+
+    # Warn if a summary longer than 140 characters was provided
+    PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
   end
 
   private
diff --git a/lib/puppet-strings/yard/tags.rb b/lib/puppet-strings/yard/tags.rb
index dd46c76..211812c 100644
--- a/lib/puppet-strings/yard/tags.rb
+++ b/lib/puppet-strings/yard/tags.rb
@@ -3,4 +3,5 @@ module PuppetStrings::Yard::Tags
   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'
 end
diff --git a/lib/puppet-strings/yard/tags/summary_tag.rb b/lib/puppet-strings/yard/tags/summary_tag.rb
new file mode 100644
index 0000000..63df5da
--- /dev/null
+++ b/lib/puppet-strings/yard/tags/summary_tag.rb
@@ -0,0 +1,9 @@
+# Implements a summary tag for general purpose short descriptions
+
+class PuppetStrings::Yard::Tags::SummaryTag < YARD::Tags::Tag
+  # Registers the tag with YARD.
+  # @return [void]
+  def self.register!
+    YARD::Tags::Library.define_tag("puppet.summary", :summary)
+  end
+end
diff --git a/lib/puppet-strings/yard/templates/default/puppet_class/html/setup.rb b/lib/puppet-strings/yard/templates/default/puppet_class/html/setup.rb
index 2250d2f..36255d3 100644
--- a/lib/puppet-strings/yard/templates/default/puppet_class/html/setup.rb
+++ b/lib/puppet-strings/yard/templates/default/puppet_class/html/setup.rb
@@ -1,7 +1,7 @@
 # Initializes the template.
 # @return [void]
 def init
-  sections :header, :box_info, :overview, T('tags'), :source
+  sections :header, :box_info, :summary, :overview, T('tags'), :source
 end
 
 # Renders the box_info section.
diff --git a/lib/puppet-strings/yard/templates/default/puppet_class/html/summary.erb b/lib/puppet-strings/yard/templates/default/puppet_class/html/summary.erb
new file mode 100644
index 0000000..75e9867
--- /dev/null
+++ b/lib/puppet-strings/yard/templates/default/puppet_class/html/summary.erb
@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>
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
index d8858fb..aa5fe0e 100644
--- 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
@@ -1,5 +1,5 @@
 # Initializes the template.
 # @return [void]
 def init
-  sections :header, :box_info, :overview, T('tags'), :source
+  sections :header, :box_info, :summary, :overview, T('tags'), :source
 end
diff --git a/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/summary.erb b/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/summary.erb
new file mode 100644
index 0000000..75e9867
--- /dev/null
+++ b/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/summary.erb
@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>
diff --git a/lib/puppet-strings/yard/templates/default/puppet_function/html/setup.rb b/lib/puppet-strings/yard/templates/default/puppet_function/html/setup.rb
index d20b4b6..c2c36b3 100644
--- a/lib/puppet-strings/yard/templates/default/puppet_function/html/setup.rb
+++ b/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, :overview, [T('tags'), :source]
+  sections :header, :box_info, :summary, :overview, [T('tags'), :source]
 end
diff --git a/lib/puppet-strings/yard/templates/default/puppet_function/html/summary.erb b/lib/puppet-strings/yard/templates/default/puppet_function/html/summary.erb
new file mode 100644
index 0000000..75e9867
--- /dev/null
+++ b/lib/puppet-strings/yard/templates/default/puppet_function/html/summary.erb
@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>
diff --git a/lib/puppet-strings/yard/templates/default/puppet_provider/html/setup.rb b/lib/puppet-strings/yard/templates/default/puppet_provider/html/setup.rb
index 57a69a4..0ad6dce 100644
--- a/lib/puppet-strings/yard/templates/default/puppet_provider/html/setup.rb
+++ b/lib/puppet-strings/yard/templates/default/puppet_provider/html/setup.rb
@@ -1,7 +1,7 @@
 # Initializes the template.
 # @return [void]
 def init
-  sections :header, :box_info, :overview, T('tags'), :features, :confines, :defaults, :commands
+  sections :header, :box_info, :summary, :overview, T('tags'), :features, :confines, :defaults, :commands
 end
 
 # Renders the confines section.
diff --git a/lib/puppet-strings/yard/templates/default/puppet_provider/html/summary.erb b/lib/puppet-strings/yard/templates/default/puppet_provider/html/summary.erb
new file mode 100644
index 0000000..75e9867
--- /dev/null
+++ b/lib/puppet-strings/yard/templates/default/puppet_provider/html/summary.erb
@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>
diff --git a/lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb b/lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb
index d0a3043..6b2e8ac 100644
--- a/lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb
+++ b/lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb
@@ -1,7 +1,7 @@
 # Initializes the template.
 # @return [void]
 def init
-  sections :header, :box_info, :overview, T('tags'), :properties, :parameters, :features
+  sections :header, :box_info, :summary, :overview, T('tags'), :properties, :parameters, :features
 end
 
 # Renders the box_info section.
diff --git a/lib/puppet-strings/yard/templates/default/puppet_type/html/summary.erb b/lib/puppet-strings/yard/templates/default/puppet_type/html/summary.erb
new file mode 100644
index 0000000..75e9867
--- /dev/null
+++ b/lib/puppet-strings/yard/templates/default/puppet_type/html/summary.erb
@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>
diff --git a/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb
index 88ee266..597fb83 100644
--- a/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb
+++ b/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb
@@ -175,4 +175,43 @@ SOURCE
       expect(tags[1].types).to eq(['Boolean'])
     end
   end
+
+  describe 'parsing a class with a summary' do
+    context 'when the summary has fewer than 140 characters' do
+      let(:source) { <<-SOURCE
+  # A simple foo class.
+  # @summary A short summary.
+  class foo() {
+    file { '/tmp/foo':
+      ensure => present
+    }
+  }
+  SOURCE
+      }
+
+      it 'should parse the summary' do
+        expect{ subject }.to output('').to_stdout_from_any_process
+        expect(subject.size).to eq(1)
+        summary = subject.first.tags(:summary)
+        expect(summary.first.text).to eq('A short summary.')
+      end
+    end
+
+    context 'when the summary has more than 140 characters' do
+      let(:source) { <<-SOURCE
+  # A simple foo class.
+  # @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!
+  class foo() {
+    file { '/tmp/foo':
+      ensure => present
+    }
+  }
+  SOURCE
+      }
+
+      it 'should log a warning' do
+        expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_class 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
+      end
+    end
+  end
 end
diff --git a/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb
index a6e46cc..24035f2 100644
--- a/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb
+++ b/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb
@@ -175,4 +175,50 @@ SOURCE
       expect(tags[1].types).to eq(['Boolean'])
     end
   end
+
+  describe 'parsing a defined type with a summary' do
+
+    context 'when the summary has fewer than 140 characters' do
+      let(:source) { <<-SOURCE
+# A simple foo defined type.
+# @summary A short summary.
+# @param param1 First param.
+# @param [Boolean] param2 Second param.
+# @param param3 Third param.
+define foo(Integer $param1, $param2, String $param3 = hi) {
+  file { '/tmp/foo':
+    ensure => present
+  }
+}
+SOURCE
+      }
+
+      it 'should parse the summary' do
+        expect{ subject }.to output('').to_stdout_from_any_process
+        expect(subject.size).to eq(1)
+        summary = subject.first.tags(:summary)
+        expect(summary.first.text).to eq('A short summary.')
+      end
+    end
+
+    context 'when the summary has more than 140 characters' do
+      let(:source) { <<-SOURCE
+# A simple foo defined type.
+# @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!
+# @param param1 First param.
+# @param [Boolean] param2 Second param.
+# @param param3 Third param.
+define foo(Integer $param1, $param2, String $param3 = hi) {
+  file { '/tmp/foo':
+    ensure => present
+  }
+}
+SOURCE
+      }
+
+      it 'should log a warning' do
+        expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_defined_type 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
+      end
+    end
+  end
 end
diff --git a/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb
index b58d3ca..54bd6b2 100644
--- a/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb
+++ b/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb
@@ -260,4 +260,41 @@ SOURCE
       expect(tags[0].types).to eq(['Any'])
     end
   end
+
+  describe 'parsing a function with a summary' do
+    context 'when the summary has fewer than 140 characters' do
+      let(:source) { <<-SOURCE
+# A simple foo function.
+# @summary A short summary.
+# @return [String] foo
+function foo() {
+  notice 'hello world'
+}
+SOURCE
+      }
+
+      it 'should parse the summary' do
+        expect{ subject }.to output('').to_stdout_from_any_process
+        expect(subject.size).to eq(1)
+        summary = subject.first.tags(:summary)
+        expect(summary.first.text).to eq('A short summary.')
+      end
+    end
+
+    context 'when the summary has more than 140 characters' do
+      let(:source) { <<-SOURCE
+# A simple foo function.
+# @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!
+function foo() {
+  notice 'hello world'
+}
+
+SOURCE
+      }
+
+      it 'should log a warning' do
+        expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_function 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
+      end
+    end
+  end
 end
diff --git a/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb
index 7a1027b..f141155 100644
--- a/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb
+++ b/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb
@@ -654,4 +654,43 @@ end
       expect{ subject }.to output(/\[warn\]: The docstring for Puppet 4.x function 'foo' contains @return tags near \(stdin\):3: return value documentation should be made on the dispatch call\./).to_stdout_from_any_process
     end
   end
+
+  describe 'parsing a function with a summary' do
+    context 'when the summary has fewer than 140 characters' do
+      let(:source) { <<-SOURCE
+# An example 4.x function.
+# @summary A short summary.
+Puppet::Functions.create_function(:foo) do
+  # @return [Undef]
+  dispatch :foo do
+  end
+end
+SOURCE
+      }
+
+      it 'should parse the summary' do
+        expect{ subject }.to output('').to_stdout_from_any_process
+        expect(subject.size).to eq(1)
+        summary = subject.first.tags(:summary)
+        expect(summary.first.text).to eq('A short summary.')
+      end
+    end
+
+    context 'when the summary has more than 140 characters' do
+      let(:source) { <<-SOURCE
+# An example 4.x function.
+# @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!
+Puppet::Functions.create_function(:foo) do
+  # @return [Undef]
+  dispatch :foo do
+  end
+end
+SOURCE
+      }
+
+      it 'should log a warning' do
+        expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_function 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
+      end
+    end
+  end
 end
diff --git a/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb
index 3f4b23a..3daa8ba 100644
--- a/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb
+++ b/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb
@@ -105,4 +105,35 @@ SOURCE
       expect(object.commands).to eq({'foo' => '/usr/bin/foo'})
     end
   end
+
+  describe 'parsing a provider with a summary' do
+    context 'when the summary has fewer than 140 characters' do
+      let(:source) { <<-SOURCE
+Puppet::Type.type(:custom).provide :linux do
+  @doc = '@summary A short summary.'
+end
+SOURCE
+      }
+
+      it 'should parse the summary' do
+        expect{ subject }.to output('').to_stdout_from_any_process
+        expect(subject.size).to eq(1)
+        summary = subject.first.tags(:summary)
+        expect(summary.first.text).to eq('A short summary.')
+      end
+    end
+
+    context 'when the summary has more than 140 characters' do
+      let(:source) { <<-SOURCE
+Puppet::Type.type(:custom).provide :linux do
+  @doc = '@summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!'
+end
+SOURCE
+      }
+
+      it 'should log a warning' do
+        expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_provider 'linux' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
+      end
+    end
+  end
 end
diff --git a/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb
index e66c460..f1c0197 100644
--- a/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb
+++ b/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb
@@ -235,4 +235,35 @@ SOURCE
       expect(object.parameters[0].isnamevar).to eq(true)
     end
   end
+
+  describe 'parsing a type with a summary' do
+    context 'when the summary has fewer than 140 characters' do
+      let(:source) { <<-SOURCE
+Puppet::Type.newtype(:database) do
+  @doc = '@summary A short summary.'
+end
+SOURCE
+      }
+
+      it 'should parse the summary' do
+        expect{ subject }.to output('').to_stdout_from_any_process
+        expect(subject.size).to eq(1)
+        summary = subject.first.tags(:summary)
+        expect(summary.first.text).to eq('A short summary.')
+      end
+    end
+
+    context 'when the summary has more than 140 characters' do
+      let(:source) { <<-SOURCE
+Puppet::Type.newtype(:database) do
+  @doc = '@summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!'
+end
+SOURCE
+      }
+
+      it 'should log a warning' do
+        expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_type 'database' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
+      end
+    end
+  end
 end

From 8178c0beffcf0f2773fd89878745ee0d971665bf Mon Sep 17 00:00:00 2001
From: Will Hopper <whopper@puppetlabs.com>
Date: Wed, 15 Mar 2017 16:43:04 -0700
Subject: [PATCH 2/3] (PDOC-161) Update README with an example usage of the
 summary tag

---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index a02f557..d5007c6 100644
--- a/README.md
+++ b/README.md
@@ -190,6 +190,8 @@ To document Puppet classes and defined types, use a series of comments to create
 #
 # This is an example of how to document a Puppet class
 #
+# @summary A short summary of the purpose of the class.
+#
 # @example Declaring the class
 #   include example
 #
@@ -206,6 +208,7 @@ class example_class(
 The Strings elements appearing in the above comment block are:
 
 * Three comment lines, not prefixed with tags, give the class description.
+* The `@summary` YARD tag, which can be used for a short description of the class (fewer than 140 characters recommended).
 * The `@example` YARD tag, immediately followed by an optional title.
 * The `include` statement, which adds the usage example code.
 * Two `@param` tags, with the name of the parameter first, followed by a string describing the parameter's purpose.

From a3f00d043f6b6b86607129c2b35bf13b28754910 Mon Sep 17 00:00:00 2001
From: Will Hopper <whopper@puppetlabs.com>
Date: Thu, 16 Mar 2017 14:01:22 -0700
Subject: [PATCH 3/3] (maint) Update outdated rubocop checks

---
 .rubocop.yml | 5 ++++-
 Gemfile      | 6 +++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/.rubocop.yml b/.rubocop.yml
index 91b2a9f..ccd6d11 100644
--- a/.rubocop.yml
+++ b/.rubocop.yml
@@ -76,6 +76,9 @@ Style/RedundantSelf:
 Metrics/MethodLength:
   Enabled: false
 
+Metrics/ModuleLength:
+  Enabled: false
+
 # DISABLED - not useful
 Style/WhileUntilModifier:
   Enabled: false
@@ -318,7 +321,7 @@ Style/EmptyLiteral:
 Metrics/LineLength:
   Enabled: false
 
-Style/MethodCallParentheses:
+Style/MethodCallWithoutArgsParentheses:
   Enabled: false
 
 Style/MethodDefParentheses:
diff --git a/Gemfile b/Gemfile
index eb72b2b..69c8cc8 100644
--- a/Gemfile
+++ b/Gemfile
@@ -34,6 +34,6 @@ group :development do
   end
 end
 
-gem 'json',      '<= 1.8'   if RUBY_VERSION < '2.0.0'
-gem 'json_pure', '<= 2.0.1' if RUBY_VERSION < '2.0.0'
-gem 'rubocop'               if RUBY_VERSION >= '2.0.0'
+gem 'json',      '<= 1.8'    if RUBY_VERSION < '2.0.0'
+gem 'json_pure', '<= 2.0.1'  if RUBY_VERSION < '2.0.0'
+gem 'rubocop',   '<= 0.47.0' if RUBY_VERSION >= '2.0.0'