From 176d6d4d8c2c9b1d46e35780d5085783fc44ad28 Mon Sep 17 00:00:00 2001
From: Eric Putnam <putnam.eric@gmail.com>
Date: Mon, 12 Feb 2018 16:11:52 -0800
Subject: [PATCH] (PDOC-184) refactoring because naming is hard

---
 lib/puppet-strings/markdown.rb                       | 12 ++++++------
 lib/puppet-strings/markdown/base.rb                  |  9 ++++++---
 .../{puppet_resource_type.rb => custom_type.rb}      |  6 +++---
 .../{puppet_resource_types.rb => custom_types.rb}    |  8 ++++----
 .../{puppet_defined_type.rb => defined_type.rb}      |  4 ++--
 .../{puppet_defined_types.rb => defined_types.rb}    |  8 ++++----
 .../markdown/{puppet_function.rb => function.rb}     |  6 +++---
 .../markdown/{puppet_functions.rb => functions.rb}   |  8 ++++----
 lib/puppet-strings/markdown/puppet_class.rb          |  2 +-
 lib/puppet-strings/markdown/table_of_contents.rb     |  8 +++-----
 .../{puppet_resource.erb => classes_and_defines.erb} |  0
 .../{puppet_resource_type.erb => custom_type.erb}    |  0
 .../templates/{puppet_function.erb => function.erb}  |  0
 spec/fixtures/unit/markdown/output.md                | 12 ++++++------
 spec/unit/puppet-strings/markdown_spec.rb            |  3 +--
 15 files changed, 43 insertions(+), 43 deletions(-)
 rename lib/puppet-strings/markdown/{puppet_resource_type.rb => custom_type.rb} (77%)
 rename lib/puppet-strings/markdown/{puppet_resource_types.rb => custom_types.rb} (65%)
 rename lib/puppet-strings/markdown/{puppet_defined_type.rb => defined_type.rb} (73%)
 rename lib/puppet-strings/markdown/{puppet_defined_types.rb => defined_types.rb} (66%)
 rename lib/puppet-strings/markdown/{puppet_function.rb => function.rb} (88%)
 rename lib/puppet-strings/markdown/{puppet_functions.rb => functions.rb} (67%)
 rename lib/puppet-strings/markdown/templates/{puppet_resource.erb => classes_and_defines.erb} (100%)
 rename lib/puppet-strings/markdown/templates/{puppet_resource_type.erb => custom_type.erb} (100%)
 rename lib/puppet-strings/markdown/templates/{puppet_function.erb => function.erb} (100%)

diff --git a/lib/puppet-strings/markdown.rb b/lib/puppet-strings/markdown.rb
index d40d35d..909576f 100644
--- a/lib/puppet-strings/markdown.rb
+++ b/lib/puppet-strings/markdown.rb
@@ -3,9 +3,9 @@ require 'puppet-strings/json'
 # module for parsing Yard Registries and generating markdown
 module PuppetStrings::Markdown
   require_relative 'markdown/puppet_classes'
-  require_relative 'markdown/puppet_functions'
-  require_relative 'markdown/puppet_defined_types'
-  require_relative 'markdown/puppet_resource_types'
+  require_relative 'markdown/functions'
+  require_relative 'markdown/defined_types'
+  require_relative 'markdown/custom_types'
   require_relative 'markdown/table_of_contents'
 
   # generates markdown documentation
@@ -14,9 +14,9 @@ module PuppetStrings::Markdown
     final = "# Reference\n\n"
     final << PuppetStrings::Markdown::TableOfContents.render
     final << PuppetStrings::Markdown::PuppetClasses.render
-    final << PuppetStrings::Markdown::PuppetDefinedTypes.render
-    final << PuppetStrings::Markdown::PuppetResourceTypes.render
-    final << PuppetStrings::Markdown::PuppetFunctions.render
+    final << PuppetStrings::Markdown::DefinedTypes.render
+    final << PuppetStrings::Markdown::CustomTypes.render
+    final << PuppetStrings::Markdown::Functions.render
 
     final
   end
diff --git a/lib/puppet-strings/markdown/base.rb b/lib/puppet-strings/markdown/base.rb
index 936e34b..55456f2 100644
--- a/lib/puppet-strings/markdown/base.rb
+++ b/lib/puppet-strings/markdown/base.rb
@@ -57,8 +57,7 @@ module PuppetStrings::Markdown
     # e.g. {:tag_name=>"author", :text=>"eputnam"}
     { :return_val => 'return',
       :since => 'since',
-      :summary => 'summary',
-      :option => 'option' }.each do |method_name, tag_name|
+      :summary => 'summary' }.each do |method_name, tag_name|
       define_method method_name do
         @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text] unless @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0].nil?
       end
@@ -99,15 +98,19 @@ module PuppetStrings::Markdown
       @tags.select { |tag| tag[:tag_name] == 'example' } unless @tags.select { |tag| tag[:tag_name] == 'example' }[0].nil?
     end
 
-    # @return [Array] example tag hashes
+    # @return [Array] raise tag hashes
     def raises
       @tags.select { |tag| tag[:tag_name] == 'raise' } unless @tags.select { |tag| tag[:tag_name] == 'raise' }[0].nil?
     end
 
+    # @return [Array] option tag hashes
     def options
       @tags.select { |tag| tag[:tag_name] == 'option' } unless @tags.select { |tag| tag[:tag_name] == 'option' }[0].nil?
     end
 
+    # @param parameter_name
+    #   parameter name to match to option tags
+    # @return [Array] option tag hashes that have a parent parameter_name
     def options_for_param(parameter_name)
       opts_for_p = options.select { |o| o[:parent] == parameter_name } unless options.nil?
       opts_for_p unless opts_for_p.nil? || opts_for_p.length.zero?
diff --git a/lib/puppet-strings/markdown/puppet_resource_type.rb b/lib/puppet-strings/markdown/custom_type.rb
similarity index 77%
rename from lib/puppet-strings/markdown/puppet_resource_type.rb
rename to lib/puppet-strings/markdown/custom_type.rb
index 3d24fb3..967bb35 100644
--- a/lib/puppet-strings/markdown/puppet_resource_type.rb
+++ b/lib/puppet-strings/markdown/custom_type.rb
@@ -1,10 +1,10 @@
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
-  class PuppetResourceType < Base
+  class CustomType < Base
     def initialize(registry)
-      @template = 'puppet_resource_type.erb'
-      super(registry, 'resource type')
+      @template = 'custom_type.erb'
+      super(registry, 'type')
     end
 
     def render
diff --git a/lib/puppet-strings/markdown/puppet_resource_types.rb b/lib/puppet-strings/markdown/custom_types.rb
similarity index 65%
rename from lib/puppet-strings/markdown/puppet_resource_types.rb
rename to lib/puppet-strings/markdown/custom_types.rb
index e67690e..b2c9660 100644
--- a/lib/puppet-strings/markdown/puppet_resource_types.rb
+++ b/lib/puppet-strings/markdown/custom_types.rb
@@ -1,7 +1,7 @@
-require_relative 'puppet_resource_type'
+require_relative 'custom_type'
 
 module PuppetStrings::Markdown
-  module PuppetResourceTypes
+  module CustomTypes
 
     # @return [Array] list of resource types
     def self.in_rtypes
@@ -11,7 +11,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_rtypes.length > 0 ? "## Resource types\n\n" : ""
       in_rtypes.each do |type|
-        final << PuppetStrings::Markdown::PuppetResourceType.new(type).render
+        final << PuppetStrings::Markdown::CustomType.new(type).render
       end
       final
     end
@@ -20,7 +20,7 @@ module PuppetStrings::Markdown
       final = []
 
       in_rtypes.each do |type|
-        final.push(PuppetStrings::Markdown::PuppetResourceType.new(type).toc_info)
+        final.push(PuppetStrings::Markdown::CustomType.new(type).toc_info)
       end
 
       final
diff --git a/lib/puppet-strings/markdown/puppet_defined_type.rb b/lib/puppet-strings/markdown/defined_type.rb
similarity index 73%
rename from lib/puppet-strings/markdown/puppet_defined_type.rb
rename to lib/puppet-strings/markdown/defined_type.rb
index 052052c..86e5c14 100644
--- a/lib/puppet-strings/markdown/puppet_defined_type.rb
+++ b/lib/puppet-strings/markdown/defined_type.rb
@@ -1,9 +1,9 @@
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
-  class PuppetDefinedType < Base
+  class DefinedType < Base
     def initialize(registry)
-      @template = 'puppet_resource.erb'
+      @template = 'classes_and_defines.erb'
       super(registry, 'defined type')
     end
 
diff --git a/lib/puppet-strings/markdown/puppet_defined_types.rb b/lib/puppet-strings/markdown/defined_types.rb
similarity index 66%
rename from lib/puppet-strings/markdown/puppet_defined_types.rb
rename to lib/puppet-strings/markdown/defined_types.rb
index 838fb45..e23c6a3 100644
--- a/lib/puppet-strings/markdown/puppet_defined_types.rb
+++ b/lib/puppet-strings/markdown/defined_types.rb
@@ -1,7 +1,7 @@
-require_relative 'puppet_defined_type'
+require_relative 'defined_type'
 
 module PuppetStrings::Markdown
-  module PuppetDefinedTypes
+  module DefinedTypes
 
     # @return [Array] list of defined types
     def self.in_dtypes
@@ -11,7 +11,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_dtypes.length > 0 ? "## Defined types\n\n" : ""
       in_dtypes.each do |type|
-        final << PuppetStrings::Markdown::PuppetDefinedType.new(type).render
+        final << PuppetStrings::Markdown::DefinedType.new(type).render
       end
       final
     end
@@ -20,7 +20,7 @@ module PuppetStrings::Markdown
       final = []
 
       in_dtypes.each do |type|
-        final.push(PuppetStrings::Markdown::PuppetDefinedType.new(type).toc_info)
+        final.push(PuppetStrings::Markdown::DefinedType.new(type).toc_info)
       end
 
       final
diff --git a/lib/puppet-strings/markdown/puppet_function.rb b/lib/puppet-strings/markdown/function.rb
similarity index 88%
rename from lib/puppet-strings/markdown/puppet_function.rb
rename to lib/puppet-strings/markdown/function.rb
index d9024a6..5680d9e 100644
--- a/lib/puppet-strings/markdown/puppet_function.rb
+++ b/lib/puppet-strings/markdown/function.rb
@@ -1,11 +1,11 @@
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
-  class PuppetFunction < Base
+  class Function < Base
     attr_reader :signatures
 
     def initialize(registry)
-      @template = 'puppet_function.erb'
+      @template = 'function.erb'
       super(registry, 'function')
       @signatures = []
       registry[:signatures].each do |sig|
@@ -39,7 +39,7 @@ module PuppetStrings::Markdown
     end
   end
 
-  class PuppetFunction::Signature < Base
+  class Function::Signature < Base
     def initialize(registry)
       @registry = registry
       super(@registry, 'function signature')
diff --git a/lib/puppet-strings/markdown/puppet_functions.rb b/lib/puppet-strings/markdown/functions.rb
similarity index 67%
rename from lib/puppet-strings/markdown/puppet_functions.rb
rename to lib/puppet-strings/markdown/functions.rb
index 5b0e177..1996938 100644
--- a/lib/puppet-strings/markdown/puppet_functions.rb
+++ b/lib/puppet-strings/markdown/functions.rb
@@ -1,7 +1,7 @@
-require_relative 'puppet_function'
+require_relative 'function'
 
 module PuppetStrings::Markdown
-  module PuppetFunctions
+  module Functions
 
     # @return [Array] list of functions
     def self.in_functions
@@ -11,7 +11,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_functions.length > 0 ? "## Functions\n\n" : ""
       in_functions.each do |func|
-        final << PuppetStrings::Markdown::PuppetFunction.new(func).render
+        final << PuppetStrings::Markdown::Function.new(func).render
       end
       final
     end
@@ -20,7 +20,7 @@ module PuppetStrings::Markdown
       final = []
 
       in_functions.each do |func|
-        final.push(PuppetStrings::Markdown::PuppetFunction.new(func).toc_info)
+        final.push(PuppetStrings::Markdown::Function.new(func).toc_info)
       end
 
       final
diff --git a/lib/puppet-strings/markdown/puppet_class.rb b/lib/puppet-strings/markdown/puppet_class.rb
index 7907acb..8bf02be 100644
--- a/lib/puppet-strings/markdown/puppet_class.rb
+++ b/lib/puppet-strings/markdown/puppet_class.rb
@@ -3,7 +3,7 @@ require 'puppet-strings/markdown/base'
 module PuppetStrings::Markdown
   class PuppetClass < Base
     def initialize(registry)
-      @template = 'puppet_resource.erb'
+      @template = 'classes_and_defines.erb'
       super(registry, 'class')
     end
 
diff --git a/lib/puppet-strings/markdown/table_of_contents.rb b/lib/puppet-strings/markdown/table_of_contents.rb
index ec9a660..16f5726 100644
--- a/lib/puppet-strings/markdown/table_of_contents.rb
+++ b/lib/puppet-strings/markdown/table_of_contents.rb
@@ -1,12 +1,10 @@
-require 'puppet-strings/markdown/puppet_classes'
-
 module PuppetStrings::Markdown
   module TableOfContents
     def self.render
       puppet_classes = PuppetStrings::Markdown::PuppetClasses.toc_info
-      puppet_defined_types = PuppetStrings::Markdown::PuppetDefinedTypes.toc_info
-      puppet_resource_types = PuppetStrings::Markdown::PuppetResourceTypes.toc_info
-      puppet_functions = PuppetStrings::Markdown::PuppetFunctions.toc_info
+      puppet_defined_types = PuppetStrings::Markdown::DefinedTypes.toc_info
+      puppet_resource_types = PuppetStrings::Markdown::CustomTypes.toc_info
+      puppet_functions = PuppetStrings::Markdown::Functions.toc_info
 
       template = File.join(File.dirname(__FILE__),"templates/table_of_contents.erb")
       ERB.new(File.read(template), nil, '-').result(binding)
diff --git a/lib/puppet-strings/markdown/templates/puppet_resource.erb b/lib/puppet-strings/markdown/templates/classes_and_defines.erb
similarity index 100%
rename from lib/puppet-strings/markdown/templates/puppet_resource.erb
rename to lib/puppet-strings/markdown/templates/classes_and_defines.erb
diff --git a/lib/puppet-strings/markdown/templates/puppet_resource_type.erb b/lib/puppet-strings/markdown/templates/custom_type.erb
similarity index 100%
rename from lib/puppet-strings/markdown/templates/puppet_resource_type.erb
rename to lib/puppet-strings/markdown/templates/custom_type.erb
diff --git a/lib/puppet-strings/markdown/templates/puppet_function.erb b/lib/puppet-strings/markdown/templates/function.erb
similarity index 100%
rename from lib/puppet-strings/markdown/templates/puppet_function.erb
rename to lib/puppet-strings/markdown/templates/function.erb
diff --git a/spec/fixtures/unit/markdown/output.md b/spec/fixtures/unit/markdown/output.md
index b7177d5..0f8db8c 100644
--- a/spec/fixtures/unit/markdown/output.md
+++ b/spec/fixtures/unit/markdown/output.md
@@ -6,7 +6,7 @@
 * [`klass::dt`](#klassdt): A simple defined type.
 ## Resource types
 * [`apt_key`](#apt_key): Example resource type using the new API.
-* [`database`](#database): An example database server resource type.
+* [`database`](#database): An example database server type.
 ## Functions
 * [`func`](#func): A simple Puppet function.
 * [`func4x`](#func4x): An example 4.x function.
@@ -154,7 +154,7 @@ apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
 
 #### Properties
 
-The following properties are available in the `apt_key` resource type.
+The following properties are available in the `apt_key` type.
 
 ##### `ensure`
 
@@ -170,7 +170,7 @@ Date the key was created, in ISO format.
 
 #### Parameters
 
-The following parameters are available in the `apt_key` resource type.
+The following parameters are available in the `apt_key` type.
 
 ##### `id`
 
@@ -184,7 +184,7 @@ The ID of the key you want to manage.
 
 ### database
 
-An example database server resource type.
+An example database server type.
 
 #### Examples
 ##### here's an example
@@ -196,7 +196,7 @@ database { 'foo':
 
 #### Properties
 
-The following properties are available in the `database` resource type.
+The following properties are available in the `database` type.
 
 ##### `ensure`
 
@@ -222,7 +222,7 @@ Default value: warn
 
 #### Parameters
 
-The following parameters are available in the `database` resource type.
+The following parameters are available in the `database` type.
 
 ##### `address`
 
diff --git a/spec/unit/puppet-strings/markdown_spec.rb b/spec/unit/puppet-strings/markdown_spec.rb
index fed6487..1adb923 100644
--- a/spec/unit/puppet-strings/markdown_spec.rb
+++ b/spec/unit/puppet-strings/markdown_spec.rb
@@ -1,6 +1,5 @@
 require 'spec_helper'
 require 'puppet-strings/markdown'
-require 'puppet-strings/markdown/puppet_classes'
 require 'puppet-strings/markdown/table_of_contents'
 require 'tempfile'
 
@@ -125,7 +124,7 @@ end
 
 Puppet::Type.newtype(:database) do
   desc <<-DESC
-An example database server resource type.
+An example database server type.
 @option opts :foo bar
 @raise SomeError
 @example here's an example