From 64d7b0e4dbdf26b8a6c6693a7d701a1ab453df81 Mon Sep 17 00:00:00 2001
From: Eric Putnam <putnam.eric@gmail.com>
Date: Mon, 29 Jan 2018 15:44:31 -0800
Subject: [PATCH] (maint) add condition for misleading warning

There is a warning that displays when there is no text outside of tags for a given component, this text would become the 'Overview' section. The warning says: `[warn]: Missing documentation for Puppet class 'klass' at (stdin):4` The problem is that if the user has instead used the @summary tag, and is then using only tags, strings will report this warning even though there is clearly documentation. This adds a condition for the warning: If there is no text AND there are no tags, THEN output a warning saying there is no documentation.
---
 lib/puppet-strings/yard/handlers/puppet/class_handler.rb        | 2 +-
 lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb | 2 +-
 lib/puppet-strings/yard/handlers/puppet/function_handler.rb     | 2 +-
 lib/puppet-strings/yard/handlers/ruby/function_handler.rb       | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/lib/puppet-strings/yard/handlers/puppet/class_handler.rb b/lib/puppet-strings/yard/handlers/puppet/class_handler.rb
index e026b02..b13772f 100644
--- a/lib/puppet-strings/yard/handlers/puppet/class_handler.rb
+++ b/lib/puppet-strings/yard/handlers/puppet/class_handler.rb
@@ -13,7 +13,7 @@ class PuppetStrings::Yard::Handlers::Puppet::ClassHandler < PuppetStrings::Yard:
     register object
 
     # Log a warning if missing documentation
-    log.warn "Missing documentation for Puppet class '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty?
+    log.warn "Missing documentation for Puppet class '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty?
 
     # Set the parameter types
     set_parameter_types(object)
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 2d03f6b..b2a32bd 100644
--- a/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb
+++ b/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb
@@ -13,7 +13,7 @@ class PuppetStrings::Yard::Handlers::Puppet::DefinedTypeHandler < PuppetStrings:
     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?
+    log.warn "Missing documentation for Puppet defined type '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty?
 
     # Set the parameter types
     set_parameter_types(object)
diff --git a/lib/puppet-strings/yard/handlers/puppet/function_handler.rb b/lib/puppet-strings/yard/handlers/puppet/function_handler.rb
index 579fcd4..e84f106 100644
--- a/lib/puppet-strings/yard/handlers/puppet/function_handler.rb
+++ b/lib/puppet-strings/yard/handlers/puppet/function_handler.rb
@@ -15,7 +15,7 @@ class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Ya
     register object
 
     # Log a warning if missing documentation
-    log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty?
+    log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty?
 
     # Set the parameter tag types
     set_parameter_types(object)
diff --git a/lib/puppet-strings/yard/handlers/ruby/function_handler.rb b/lib/puppet-strings/yard/handlers/ruby/function_handler.rb
index 2ee27fb..52d0da6 100644
--- a/lib/puppet-strings/yard/handlers/ruby/function_handler.rb
+++ b/lib/puppet-strings/yard/handlers/ruby/function_handler.rb
@@ -77,7 +77,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
   end
 
   def add_tags(object)
-    log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty?
+    log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty?
     log.warn "The docstring for Puppet 4.x function '#{object.name}' contains @param tags near #{object.file}:#{object.line}: parameter documentation should be made on the dispatch call." unless object.tags(:param).empty?
     log.warn "The docstring for Puppet 4.x function '#{object.name}' contains @return tags near #{object.file}:#{object.line}: return value documentation should be made on the dispatch call." unless object.tags(:return).empty?
     log.warn "The docstring for Puppet 4.x function '#{object.name}' contains @overload tags near #{object.file}:#{object.line}: overload tags are automatically generated from the dispatch calls." unless object.tags(:overload).empty?