Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

(PDOC-161) Add summary tag for short descriptions #138

Merged
merged 3 commits into from
Mar 16, 2017
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .rubocop.yml
Original file line number Diff line number Diff line change
@@ -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:
6 changes: 3 additions & 3 deletions Gemfile
Original file line number Diff line number Diff line change
@@ -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'
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 3 additions & 0 deletions lib/puppet-strings/yard.rb
Original file line number Diff line number Diff line change
@@ -24,6 +24,9 @@ def self.setup!
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
8 changes: 8 additions & 0 deletions lib/puppet-strings/yard/handlers/helpers.rb
Original file line number Diff line number Diff line change
@@ -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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@scotje I stuck this in this Helper module for the Handlers. Does that seem reasonable?

log.warn "The length of the summary for #{object.type} '#{object.name}' exceeds the recommended limit of 140 characters."
end
end
end
4 changes: 4 additions & 0 deletions lib/puppet-strings/yard/handlers/puppet/class_handler.rb
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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
4 changes: 4 additions & 0 deletions lib/puppet-strings/yard/handlers/puppet/function_handler.rb
Original file line number Diff line number Diff line change
@@ -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
4 changes: 4 additions & 0 deletions lib/puppet-strings/yard/handlers/ruby/function_handler.rb
Original file line number Diff line number Diff line change
@@ -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
4 changes: 4 additions & 0 deletions lib/puppet-strings/yard/handlers/ruby/provider_handler.rb
Original file line number Diff line number Diff line change
@@ -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
4 changes: 4 additions & 0 deletions lib/puppet-strings/yard/handlers/ruby/type_handler.rb
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions lib/puppet-strings/yard/tags.rb
Original file line number Diff line number Diff line change
@@ -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
9 changes: 9 additions & 0 deletions lib/puppet-strings/yard/tags/summary_tag.rb
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
<% if object.docstring.has_tag?(:summary) %>
<h2>Summary</h2>
<%= object.docstring.tag(:summary).text %>
<% end %>
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
<% if object.docstring.has_tag?(:summary) %>
<h2>Summary</h2>
<%= object.docstring.tag(:summary).text %>
<% end %>
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
<% if object.docstring.has_tag?(:summary) %>
<h2>Summary</h2>
<%= object.docstring.tag(:summary).text %>
<% end %>
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
<% if object.docstring.has_tag?(:summary) %>
<h2>Summary</h2>
<%= object.docstring.tag(:summary).text %>
<% end %>
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
<% if object.docstring.has_tag?(:summary) %>
<h2>Summary</h2>
<%= object.docstring.tag(:summary).text %>
<% end %>
Original file line number Diff line number Diff line change
@@ -175,4 +175,43 @@ class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {
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
Original file line number Diff line number Diff line change
@@ -175,4 +175,50 @@
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
Original file line number Diff line number Diff line change
@@ -260,4 +260,41 @@
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
Loading