(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

@@ -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

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

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

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

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

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

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

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

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

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

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.

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 %>

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

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 %>

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

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 %>

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.

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 %>

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.

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 %>

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

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

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

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

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

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