Merge pull request #138 from whopper/PDOC-161/master/summary

(PDOC-161) Add `summary` tag for short descriptions

.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:

Gemfile

@@ -34,6 +34,6 @@ group :development do
   end
 end
 
-gem 'json',      '<= 1.8'   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 'json_pure', '<= 2.0.1'  if RUBY_VERSION < '2.0.0'
-gem 'rubocop'               if RUBY_VERSION >= '2.0.0'
+gem 'rubocop',   '<= 0.47.0' if RUBY_VERSION >= '2.0.0'

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.

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