(PDOC-184) refactoring because naming is hard

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

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?

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

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

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
 

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

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')

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

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
 

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)

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`
 

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