puppet-strings 0.4.0 → 0.99.0

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/html/setup.rb

@@ -1 +0,0 @@
-include T('default/module/html')

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb

@@ -1,91 +0,0 @@
-include T('default/module')
-
-require File.join(File.dirname(__FILE__),'../html_helper')
-require File.join(File.dirname(__FILE__),'../template_helper')
-
-def init
-  sections :header, :box_info,
-    :method_summary, [:item_summary],
-    :method_details_list, [T('method_details')]
-
-  @methods = object.children
-  @template_helper = TemplateHelper.new
-end
-
-def header
-  # The list is expected to only contain one type of function
-  if @methods[0]['puppet_4x_function']
-    @header_text = "Puppet 4 Functions"
-  else
-    @header_text = "Puppet 3 Functions"
-  end
-
-  erb(:header)
-end
-
-def box_info
-  @source_files = []
-
-  @methods.each do |method|
-    # extract the file name and line number for each method
-    file_name = method.files[0][0]
-    line_number = method.files[0][1]
-
-    @source_files.push([method.name, "#{file_name} (#{line_number})"])
-  end
-
-  erb(:box_info)
-end
-
-def method_summary
-  @method_details = []
-  @html_helper = HTMLHelper.new
-
-  @methods.each do |method|
-    # If there are multiple sentences in the method description, only
-    # use the first one for the summary. If the author did not include
-    # any periods in their summary, include the whole thing
-    first_sentence = method.docstring.match(/^(.*?)\./)
-    brief_summary = first_sentence ? first_sentence : method.docstring
-
-    return_tag = method.tags.find { |tag| tag.tag_name == "return"}
-    return_types = return_tag.nil? ? nil : return_tag.types
-
-    @method_details.push({:name => method.name, :short_desc => brief_summary, :return_types => return_types})
-  end
-
-  erb(:method_summary)
-end
-
-def method_details_list
-  @class_details = []
-  @html_helper = HTMLHelper.new
-
-  @methods.each do |object|
-
-    method_info = @template_helper.extract_tag_data(object)
-    param_details = nil
-    param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
-
-    if object['puppet_4x_function']
-      # Extract the source code
-      source_code = object.source
-      # Extract the parameters for the source code
-      parameters = source_code.match(/(?:def .*)\((.*?)\)/)
-      # Convert the matched string into an array of strings
-      params = parameters.nil? ? nil :  parameters[1].split(/\s*,\s*/)
-
-      param_details = @template_helper.extract_param_details(params, param_tags) unless params.nil?
-      @template_helper.check_types_match_docs object, param_details
-      @template_helper.check_parameters_match_docs object
-    else
-      param_details = @template_helper.comment_only_param_details(param_tags)
-    end
-
-    method_info[:params] = param_details
-
-    @class_details.push(method_info)
-  end
-
-  erb(:method_details_list)
-end

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/template_helper.rb

@@ -1,192 +0,0 @@
-require "puppet"
-
-# A class containing helper methods to aid in the extraction of relevant data
-# from comments and YARD tags
-class TemplateHelper
-  # Extracts data from comments which include the supported YARD tags
-  def extract_tag_data(object)
-    examples = Hash.new
-    example_tags = object.tags.find_all { |tag| tag.tag_name == "example" }
-    example_tags.each do |example|
-      examples["#{example.name}"] = example.text
-    end
-
-    return_tag = object.tags.find { |tag| tag.tag_name == "return"}
-    return_text = return_tag.nil? ? nil : return_tag.text
-    return_types = return_tag.nil? ? nil : return_tag.types
-    return_details = (return_text.nil? && return_types.nil?) ? nil : [return_text, return_types]
-
-    since_tag = object.tags.find { |tag| tag.tag_name == "since"}
-    since_text = since_tag.nil? ? nil : since_tag.text
-
-    {:name => object.name, :desc => object.docstring, :examples => examples, :since => since_text, :return => return_details}
-  end
-
-  # Given the parameter information and YARD param tags, extracts the
-  # useful information and returns it as an array of hashes which can
-  # be printed and formatted as HTML
-  #
-  # @param parameters [Array] parameter details obtained programmatically
-  # @param tags_hash [Array] parameter details obtained from comments
-  # @param fq_name [Boolean] does this parameter have a fully qualified name?
-  #
-  # @return [Hash] The relevant information about each parameter with the following keys/values:
-  #   {:name    => [String] The name of the parameter
-  #    :fq_name => [String] The fully qualified parameter name
-  #    :desc    => [String] The description provided in the comment
-  #    :types   => [Array] The parameter type(s) specified in the comment
-  #    :exists  => [Boolean] True only if the parameter exists in the documented logic and not just in a comment}
-  def extract_param_details(parameters, tags_hash, fq_name = false)
-    parameter_info = []
-
-    # Extract the information for parameters that exist
-    # as opposed to parameters that are defined only in the comments
-    parameters.each do |param|
-      if fq_name
-        param_name = param[0]
-        fully_qualified_name = param[1]
-      else
-        param_name = param
-      end
-
-      param_tag = tags_hash.find { |tag| tag.name == param_name }
-
-      description = param_tag.nil? ? nil : param_tag.text
-      param_types = param_tag.nil? ? nil : param_tag.types
-
-      param_details = {:name => param_name, :desc => description, :types => param_types, :exists? => true}
-
-      if fq_name
-        param_details[:fq_name] = fully_qualified_name
-      end
-
-      parameter_info.push(param_details)
-    end
-
-    # Check if there were any comments for parameters that do not exist
-    tags_hash.each do |tag|
-      param_exists = false
-      parameter_info.each do |parameter|
-        if parameter[:name] == tag.name
-          param_exists = true
-        end
-      end
-      if !param_exists
-        parameter_info.push({:name => tag.name, :desc => tag.text, :types => tag.types, :exists? => false})
-      end
-    end
-
-    parameter_info
-  end
-
-  # Generates parameter information in situations where the information can only
-  # come from YARD tags in the comments, not from the code itself. For now the only
-  # use for this is 3x functions. In this case exists? will always be true since we
-  # cannot verify if the parameter exists in the code itself. We must trust the user
-  # to provide information in the comments that is accurate.
-  #
-  # @param param_tags [Array] parameter details obtained from comments
-  #
-  # @return [Hash] The relevant information about each parameter with the following keys/values:
-  #   {:name          => [String] The name of the parameter
-  #    :desc          => [String] The description provided in the comment
-  #    :types         => [Array] The parameter type(s) specified in the comment
-  #    :exists        => [Boolean] True only if the parameter exists in the documented logic and not just in a comment
-  #    :puppet_3_func => [Boolean] Are these parameters for a puppet 3 function? (relevant in HTML generation)}
-  def comment_only_param_details(param_tags)
-    return if param_tags.empty?
-
-    parameter_info = []
-
-    param_tags.each do |tag|
-      parameter_info.push({:name => tag.name, :desc => tag.text, :types => tag.types, :exists? => true, :puppet_3_func => true})
-    end
-
-    parameter_info
-  end
-
-  # Check that any types specified in the docstrings match the actual method
-  # types. This is used by puppet 4x functions and defined types.
-  # @param object the code object to examine for parameters names
-  def check_types_match_docs(object, params_hash)
-    # We'll need this to extract type info from the type specified by the
-    # docstring.
-    type_parser = Puppet::Pops::Types::TypeParser.new
-    type_calculator = Puppet::Pops::Types::TypeCalculator.new
-
-    object.type_info.each do |function|
-      function.keys.each do |key|
-        if function[key].class == String
-          begin
-            instantiated = type_parser.parse function[key]
-          rescue Puppet::ParseError
-            # Likely the result of a malformed type
-            next
-          end
-        else
-          instantiated = function[key]
-        end
-        params_hash.each do |param|
-          if param[:name] == key and param[:types] != nil
-            param[:types].each do |type|
-              param_instantiated = type_parser.parse type
-              if not type_calculator.assignable? instantiated, param_instantiated
-                actual_types = object.type_info.map do |sig|
-                  sig[key].to_s if sig[key]
-                end.compact
-                # Get the locations where the object can be found. We only care about
-                # the first one.
-                locations = object.files
-                warning = <<-EOS
-[warn]: @param tag types do not match the code. The #{param[:name]}
-    parameter is declared as types #{param[:types]} in the docstring,
-    but the code specifies the types #{actual_types}
- EOS
-
-                # If the locations aren't in the shape we expect then report that
-                # the file number couldn't be determined.
-                if locations.length >= 1 and locations[0].length == 2
-                  file = locations[0][0]
-                  line = locations[0][1]
-                  warning += "    in the file #{file} near line #{line}."
-                else
-                  warning += "    Sorry, the file and line number could " +
-                             "not be determined."
-                end
-                $stderr.puts warning
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-
-  # Check that the actual function parameters match what is stated in the docs.
-  # If there is a mismatch, print a warning to stderr.
-  # This is necessary for puppet classes and defined types. This type of
-  # warning will be issued for ruby code by the ruby docstring parser.
-  # @param object the code object to examine for parameters names
-  def check_parameters_match_docs(object)
-    param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
-    names = object.parameters.map {|l| l.first.gsub(/\W/, '') }
-    locations = object.files
-    param_tags.each do |tag|
-      if not names.include?(tag.name)
-        if locations.length >= 1 and locations[0].length == 2
-          file_name = locations[0][0]
-          line_number = locations[0][1]
-          $stderr.puts <<-EOS
-[warn]: The parameter #{tag.name} is documented, but doesn't exist in
-    your code, in file #{file_name} near line #{line_number}.
-EOS
-        else
-          $stderr.puts <<-EOS
-[warn]: The parameter #{tag.name} is documented, but doesn't exist in
-    your code. Sorry, the file and line number could not be determined.
-EOS
-        end
-      end
-    end
-  end
-end

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/docstring.erb

@@ -1,34 +0,0 @@
-<div class="docstring">
-  <div class="discussion">
-    <p><%= htmlify(Puppet::Util::Docs::scrub(@class_details[:desc])) %></p>
-  </div>
-</div>
-<div class="tags">
-  <% if @class_details[:examples] != {}%>
-    <div class="examples">
-    <p class="tag_title">Examples:</p>
-    <% @class_details[:examples].each do |title, text| %>
-      <div class="inline"><p><%= title %></p></div>
-      <pre class="example code"><code><span><%= text %></span></code></pre>
-    <% end %>
-    </div>
-  <% end %>
-  <% if @class_details[:since] %>
-    <p class="tag_title">Since:</p>
-    <ul class="since">
-      <li>
-        <div class="inline">
-          <p><%= @class_details[:since] %></p>
-        </div>
-      </li>
-    </ul>
-  <% end %>
-  <% if @class_details[:return] %>
-    <p class="tag_title">Return:</p>
-    <ul class="return">
-      <li>
-        <%= @html_helper.generate_return_types(@class_details[:return][1], @class_details[:return][0]) %>
-      </li>
-    </ul>
-  <% end %>
-</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/header.erb

@@ -1,5 +0,0 @@
-<div class='module_header'>
-  <h1>
-    <%= @header_text %>
-  </h1>
-</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/parameter_details.erb

@@ -1,12 +0,0 @@
-<h2>Parameter Summary</h2>
-<div class="tags">
-  <ul class="param">
-    <%= @html_helper.generate_parameters(@param_details, object) %>
-  </ul>
-</div>
-<h2>Features</h2>
-<div class="tags">
-  <ul class="feature">
-    <%= @html_helper.generate_features(@feature_details, object) %>
-  </ul>
-</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/provider_details.erb

@@ -1,10 +0,0 @@
-<h2>Available Providers</h2>
-<% if @providers != [] %>
-<div class="tags">
-  <ul class="command">
-    <% @providers.each do |provider| %>
-      <li><a href="<%= provider.name.to_s %>.html"><tt><%= provider.name.to_s %></tt></a></li>
-    <% end %>
-  </ul>
-</div>
-<% end %>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/setup.rb

@@ -1 +0,0 @@
-include T('default/module/html')

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/setup.rb

@@ -1,55 +0,0 @@
-include T('default/module')
-
-require File.join(File.dirname(__FILE__),'../html_helper')
-require File.join(File.dirname(__FILE__),'../template_helper')
-
-def init
-  sections :header, :box_info, :pre_docstring, :docstring, :parameter_details, :provider_details
-
-  @template_helper = TemplateHelper.new
-  @html_helper = HTMLHelper.new
-end
-
-def header
-  @header_text = object.header_name
-
-  erb(:header)
-end
-
-def provider_details
-  type_name = object.name.to_s
-  @providers = YARD::Registry.all(:provider).select { |t| t.type_name == type_name }
-
-  erb(:provider_details)
-end
-
-def parameter_details
-  params = object.parameter_details.map { |h| h[:name] }
-  # Put properties and parameters in one big list where the descriptions are
-  # scrubbed and htmlified and the namevar is the first element, the ensure
-  # property the second, and the rest are alphabetized.
-  @param_details = (object.parameter_details + object.property_details).each {
-    |h| h[:desc] = htmlify(Puppet::Util::Docs::scrub(h[:desc])) if h[:desc]
-  }.sort { |a, b| a[:name] <=> b[:name] }
-  # Float ensurable and namevars to the top of the list
-  @param_details = @param_details.partition{|a| a[:name] == 'ensure'}.flatten
-  @param_details = @param_details.partition{|a| a[:namevar]}.flatten
-
-  @feature_details = object.features
-  @template_helper.check_parameters_match_docs object
-
-  erb(:parameter_details)
-end
-
-def header
-  @header_text = "Puppet Type: #{object.name}"
-
-  erb(:header)
-end
-
-def docstring
-
-  @class_details = @template_helper.extract_tag_data(object)
-
-  erb(:docstring)
-end