puppet-strings 2.1.0 → 2.5.0

data/lib/puppet-strings/markdown/templates/function.erb

@@ -1,13 +1,16 @@
-### <%= name %>
+### `<%= name %>`
 
 Type: <%= type %>
 
 <% if text -%>
 <%= text %>
+
 <% elsif summary -%>
 <%= summary %>
+
 <% else -%>
 <%= "The #{name} function." %>
+
 <% end -%>
 <% if todo -%>
 * **TODO** <%= todo %>
@@ -17,7 +20,18 @@ Type: <%= type %>
 * **Note** <%= note %>
 
 <% end -%>
+<% if examples -%>
+#### Examples
+
+<% examples.each do |eg| -%>
+##### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
 
+<% end -%>
+<% end -%>
 <% signatures.each do |sig| -%>
 #### `<%= sig.signature %>`
 
@@ -41,10 +55,23 @@ Returns: `<%= sig.return_type %>`<% if sig.return_val %> <%= sig.return_val %><%
 <% end -%>
 <% if raises -%>
 Raises:
+
 <% raises.each do |r| -%>
 * <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
 <% end -%>
 
+<% end -%>
+<% if sig.examples -%>
+##### Examples
+
+<% sig.examples.each do |eg| -%>
+###### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
 <% end -%>
 <% if sig.params -%>
 <% sig.params.each do |param| -%>
@@ -61,6 +88,14 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if sig.enums_for_param(param[:name]) -%>
+Options:
+
+<% sig.enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% end -%>
 <% end -%>

data/lib/puppet-strings/markdown/templates/puppet_task.erb

@@ -1,4 +1,4 @@
-### <%= name %>
+### `<%= name %>`
 
 <% if text -%>
 <%= text %>

data/lib/puppet-strings/markdown/templates/resource_type.erb

@@ -1,4 +1,4 @@
-### <%= name %>
+### `<%= name %>`
 
 <% if text -%>
 <%= text %>
@@ -24,10 +24,10 @@
 * **See also**
 <% see.each do |sa| -%>
 <% if sa[:name] -%>
-<%= sa[:name] %>
+<%= "  * #{sa[:name]}" %>
 <% end -%>
 <% if sa[:text] -%>
-<%= sa[:text] %>
+<%= "  * #{sa[:text]}" %>
 <% end -%>
 <% end -%>
 
@@ -44,16 +44,16 @@
 
 <% end -%>
 <% end -%>
-<% if properties -%>
+<% if properties_and_checks -%>
 #### Properties
 
 The following properties are available in the `<%= name %>` <%= @type %>.
 
-<% properties.each do |prop| -%>
+<% properties_and_checks.each do |prop| -%>
 ##### `<%= prop[:name] %>`
 
 <% if prop[:values] -%>
-Valid values: <%= prop[:values].map { |value| value_string(value) }.join(', ') %>
+Valid values: `<%= prop[:values].map { |value| value_string(value) }.join('`, `') %>`
 
 <% end -%>
 <% if prop[:isnamevar] -%>
@@ -61,7 +61,7 @@ namevar
 
 <% end -%>
 <% if prop[:aliases] -%>
-Aliases: <%= prop[:aliases].to_s.delete('{').delete('}') %>
+Aliases: `<%= prop[:aliases].to_s.delete('{').delete('}') %>`
 
 <% end -%>
 <% if prop[:data_type] -%>
@@ -77,9 +77,17 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if enums_for_param(prop[:name]) -%>
+Options:
+
+<% enums_for_param(prop[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% if prop[:default] -%>
-Default value: <%= prop[:default] %>
+Default value: `<%= prop[:default] %>`
 
 <% end -%>
 <% end -%>
@@ -93,7 +101,7 @@ The following parameters are available in the `<%= name %>` <%= @type %>.
 ##### `<%= param[:name] %>`
 
 <% if param[:values] -%>
-Valid values: <%= param[:values].map { |value| value_string(value) }.join(', ') %>
+Valid values: `<%= param[:values].map { |value| value_string(value) }.join('`, `') %>`
 
 <% end -%>
 <% if param[:isnamevar] -%>
@@ -101,14 +109,14 @@ namevar
 
 <% end -%>
 <% if param[:aliases] -%>
-Aliases: <%= param[:aliases].to_s.delete('{').delete('}') %>
+Aliases: `<%= param[:aliases].to_s.delete('{').delete('}') %>`
 
 <% end -%>
 <% if param[:data_type] -%>
 Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(param[:data_type]) %>
 
 <% end -%>
-<%= param[:description] %>
+<%= word_wrap(param[:description]) %>
 
 <% if options_for_param(param[:name]) -%>
 Options:
@@ -117,9 +125,21 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% if param[:default] -%>
-Default value: <%= value_string(param[:default]) %>
+Default value: `<%= value_string(param[:default]) %>`
+
+<% end -%>
+<% if param[:required_features] -%>
+Required features: <%= param[:required_features] %>.
 
 <% end -%>
 <% end -%>

data/lib/puppet-strings/markdown/templates/table_of_contents.erb

@@ -1,25 +1,25 @@
 <% if group.length > 0 -%>
-**<%= group_name %>**
+### <%= group_name %>
 
 <% if priv -%>
-_Public <%= group_name %>_
+#### Public <%= group_name %>
 
 <% group.each do |item| -%>
 <% unless item[:private] -%>
-* [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %>
+* [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
 
-_Private <%= group_name %>_
+#### Private <%= group_name %>
 
 <% group.each do |item| -%>
 <% if item[:private] -%>
-* `<%= item[:name] %>`: <%= item[:desc] %>
+* `<%= item[:name] %>`<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
 <% else -%>
 <% group.each do |item| -%>
-* [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %>
+* [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
 

data/lib/puppet-strings/tasks/generate.rb

@@ -33,13 +33,20 @@ namespace :strings do
         end
       end
     end
+    # rubocop:enable Style/PreferredHashMethods
 
-    [:json,:markdown].each { |format| parse_format_option(args, options, format) }
+    %i[json markdown].each { |format| parse_format_option(args, options, format) }
 
     warn('yard_args behavior is a little dodgy, use at your own risk') if args[:yard_args]
-    options[:yard_args] = args[:yard_args].split if args.has_key? :yard_args
+    options[:yard_args] = args[:yard_args].split if args.key? :yard_args
 
     PuppetStrings.generate(patterns, options)
   end
-end
 
+  namespace :generate do
+    desc 'Generate Puppet Reference documentation.'
+    task :reference, [:patterns, :debug, :backtrace] do |t, args|
+      Rake::Task['strings:generate'].invoke(args[:patterns], args[:debug], args[:backtrace], nil, 'false', 'true')
+    end
+  end
+end

data/lib/puppet-strings/version.rb

@@ -1,3 +1,3 @@
 module PuppetStrings
-  VERSION = '2.1.0'.freeze
+  VERSION = '2.5.0'.freeze
 end

data/lib/puppet-strings/yard.rb

@@ -11,6 +11,9 @@ module PuppetStrings::Yard
   # Sets up YARD for use with puppet-strings.
   # @return [void]
   def self.setup!
+    # Register our factory
+    YARD::Tags::Library.default_factory = PuppetStrings::Yard::Tags::Factory
+
     # Register the template path
     YARD::Templates::Engine.register_template_path(File.join(File.dirname(__FILE__), 'yard', 'templates'))
 
@@ -30,6 +33,9 @@ module PuppetStrings::Yard
     # Register the summary tag
     PuppetStrings::Yard::Tags::SummaryTag.register!
 
+    # Register the enum tag
+    PuppetStrings::Yard::Tags::EnumTag.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
@@ -46,6 +52,8 @@ class YARD::CLI::Yardoc
       :module,
       :class,
       :puppet_class,
+      :puppet_data_type,
+      :puppet_data_type_alias,
       :puppet_defined_type,
       :puppet_type,
       :puppet_provider,
@@ -64,6 +72,14 @@ class YARD::CLI::Stats
     output 'Puppet Classes', *type_statistics_all(:puppet_class)
   end
 
+  def stats_for_puppet_data_types
+    output 'Puppet Data Types', *type_statistics_all(:puppet_data_type)
+  end
+
+  def stats_for_puppet_data_type_aliases
+    output 'Puppet Data Type Aliases', *type_statistics_all(:puppet_data_type_alias)
+  end
+
   def stats_for_puppet_defined_types
     output 'Puppet Defined Types', *type_statistics_all(:puppet_defined_type)
   end

data/lib/puppet-strings/yard/code_objects.rb

@@ -1,6 +1,8 @@
 # The module for custom YARD code objects.
 module PuppetStrings::Yard::CodeObjects
   require 'puppet-strings/yard/code_objects/class'
+  require 'puppet-strings/yard/code_objects/data_type'
+  require 'puppet-strings/yard/code_objects/data_type_alias'
   require 'puppet-strings/yard/code_objects/defined_type'
   require 'puppet-strings/yard/code_objects/type'
   require 'puppet-strings/yard/code_objects/provider'

data/lib/puppet-strings/yard/code_objects/class.rb

@@ -50,8 +50,8 @@ class PuppetStrings::Yard::CodeObjects::Class < PuppetStrings::Yard::CodeObjects
     hash[:file] = file
     hash[:line] = line
     hash[:inherits] = statement.parent_class if statement.parent_class
-    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
-    defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
+    defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
     hash[:defaults] = defaults unless defaults.empty?
     hash[:source] = source unless source && source.empty?
     hash

data/lib/puppet-strings/yard/code_objects/data_type.rb

@@ -0,0 +1,100 @@
+require 'puppet-strings/yard/code_objects/group'
+require 'puppet-strings/yard/util'
+
+# Implements the group for Puppet DataTypes.
+class PuppetStrings::Yard::CodeObjects::DataTypes < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_data_types)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Puppet Data Types'
+  end
+end
+
+# Implements the Puppet DataType code object.
+class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObjects::Base
+  # Initializes a Puppet class code object.
+  # @param [String] The name of the Data Type
+  # @return [void]
+  def initialize(name)
+    super(PuppetStrings::Yard::CodeObjects::DataTypes.instance, name)
+    @defaults = {}
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_data_type
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    # Not implemented, but would be nice!
+    nil
+  end
+
+  def add_parameter(name, type, default)
+    tag = docstring.tags(:param).find { |item| item.name == name }
+    if tag.nil?
+      tag = YARD::Tags::Tag.new(:param, '', nil, name)
+      docstring.add_tag(tag)
+    end
+    type = [type] unless type.is_a?(Array)
+    tag.types = type if tag.types.nil?
+    set_parameter_default(name, default)
+  end
+
+  def set_parameter_default(param_name, default)
+    defaults.delete(param_name)
+    defaults[param_name] = default unless default.nil?
+  end
+
+  def parameters
+    docstring.tags(:param).map { |tag| [tag.name, defaults[tag.name]] }
+  end
+
+  def add_function(name, return_type, parameter_types)
+    meth_obj = YARD::CodeObjects::MethodObject.new(self, name, :class)
+
+    # Add return tag
+    meth_obj.add_tag(YARD::Tags::Tag.new(:return, '', return_type))
+
+    # Add parameters
+    parameter_types.each_with_index do |param_type, index|
+      meth_obj.add_tag(YARD::Tags::Tag.new(:param, '', [param_type], "param#{index + 1}"))
+    end
+
+    self.meths << meth_obj
+  end
+
+  def functions
+    meths
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring, %i[param option enum return example])
+    hash[:defaults] = defaults unless defaults.empty?
+    hash[:source] = source unless source && source.empty?
+    hash[:functions] = functions.map do |func|
+      {
+        name: func.name,
+        signature: func.signature,
+        docstring: PuppetStrings::Yard::Util.docstring_to_hash(func.docstring, %i[param option enum return example])
+      }
+    end
+    hash
+  end
+end

data/lib/puppet-strings/yard/code_objects/data_type_alias.rb

@@ -0,0 +1,58 @@
+require 'puppet-strings/yard/code_objects/group'
+require 'puppet-strings/yard/util'
+
+# Implements the group for Puppet DataTypeAliases.
+class PuppetStrings::Yard::CodeObjects::DataTypeAliases < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_data_type_aliases)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Puppet Data Type Aliases'
+  end
+end
+
+# Implements the Puppet DataTypeAlias code object.
+class PuppetStrings::Yard::CodeObjects::DataTypeAlias < PuppetStrings::Yard::CodeObjects::Base
+  attr_reader :statement
+  attr_accessor :alias_of
+
+  # Initializes a Puppet data type alias code object.
+  # @param [PuppetStrings::Parsers::DataTypeAliasStatement] statement The data type alias statement that was parsed.
+  # @return [void]
+  def initialize(statement)
+    @statement = statement
+    @alias_of = statement.alias_of
+    super(PuppetStrings::Yard::CodeObjects::DataTypeAliases.instance, statement.name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_data_type_alias
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    # Not implemented, but would be nice!
+    nil
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
+    hash[:alias_of] = alias_of
+    hash
+  end
+end