diff --git a/JSON.md b/JSON.md index e2858d2be..0f446c8e9 100644 --- a/JSON.md +++ b/JSON.md @@ -9,18 +9,19 @@ puppet strings generate --format json Document Schema =============== -At the top level, there are eight arrays in the JSON document: - -| Document Key | Description | -| ---------------- | ----------------------------------------------------------------------------- | -| puppet_classes | The list of Puppet classes that were parsed. | -| data_types | The list of data types that were parsed. | -| defined_types | The list of defined types that were parsed. | -| resource_types | The list of resource types that were parsed. | -| providers | The list of resource providers that were parsed. | -| puppet_functions | The list of Puppet functions (4.x, 4.x and Puppet language) that were parsed. | -| puppet_tasks | The list of Puppet tasks that were parsed. | -| puppet_plans | The list of Puppet plans that were parsed. | +At the top level, there are nine arrays in the JSON document: + +| Document Key | Description | +| ----------------- | ----------------------------------------------------------------------------- | +| puppet_classes | The list of Puppet classes that were parsed. | +| data_types | The list of data types that were parsed. | +| data_type_aliases | | The list of data types that were parsed. | +| defined_types | The list of defined types that were parsed. | +| resource_types | The list of resource types that were parsed. | +| providers | The list of resource providers that were parsed. | +| puppet_functions | The list of Puppet functions (4.x, 4.x and Puppet language) that were parsed. | +| puppet_tasks | The list of Puppet tasks that were parsed. | +| puppet_plans | The list of Puppet plans that were parsed. | Puppet Classes -------------- @@ -51,6 +52,20 @@ Each entry in the `data_types` list is an object with the following attributes: | defaults | The map of parameter names to default values. | | source | The ruby source code for the data type. (Not Implemented) | +Data Type Aliases +----------------- + +Each entry in the `data_type_aliases` list is an object with the following attributes: + +| Attribute Key | Description | +| ------------- | ----------------------------------------------------------------- | +| name | The name of the data type. | +| file | The file defining the data type. | +| line | The line where the data type is defined. | +| docstring | The *DocString* object for the data type (see below). | +| alias_of | The actual type this is an alias of. | +| source | The Puppet source code for the data type alias. (Not Implemented) | + Defined Types ------------- diff --git a/lib/puppet-strings/json.rb b/lib/puppet-strings/json.rb index 30743f655..ec8cfd022 100644 --- a/lib/puppet-strings/json.rb +++ b/lib/puppet-strings/json.rb @@ -9,6 +9,7 @@ def self.render(file = nil) document = { puppet_classes: YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash), data_types: YARD::Registry.all(:puppet_data_type).sort_by!(&:name).map!(&:to_hash), + data_type_aliases: YARD::Registry.all(:puppet_data_type_alias).sort_by!(&:name).map!(&:to_hash), defined_types: YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash), resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash), providers: YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash), diff --git a/lib/puppet-strings/markdown/data_type.rb b/lib/puppet-strings/markdown/data_type.rb index f1fd6cfca..903559e3a 100644 --- a/lib/puppet-strings/markdown/data_type.rb +++ b/lib/puppet-strings/markdown/data_type.rb @@ -1,10 +1,14 @@ require 'puppet-strings/markdown/base' module PuppetStrings::Markdown + # This class encapsualtes ruby data types and puppet type aliases class DataType < Base + attr_reader :alias_of + def initialize(registry) @template = 'data_type.erb' super(registry, 'data type') + @alias_of = registry[:alias_of] unless registry[:alias_of].nil? end def render diff --git a/lib/puppet-strings/markdown/data_types.rb b/lib/puppet-strings/markdown/data_types.rb index 80558ba1f..7a0fe317e 100644 --- a/lib/puppet-strings/markdown/data_types.rb +++ b/lib/puppet-strings/markdown/data_types.rb @@ -5,7 +5,10 @@ module DataTypes # @return [Array] list of data types def self.in_dtypes - arr = YARD::Registry.all(:puppet_data_type).sort_by!(&:name).map!(&:to_hash) + arr = YARD::Registry.all(:puppet_data_type).map!(&:to_hash) + arr.concat(YARD::Registry.all(:puppet_data_type_alias).map!(&:to_hash)) + + arr.sort! { |a,b| a[:name] <=> b[:name] } arr.map! { |a| PuppetStrings::Markdown::DataType.new(a) } end diff --git a/lib/puppet-strings/markdown/templates/data_type.erb b/lib/puppet-strings/markdown/templates/data_type.erb index 212fd1aad..6306b69d2 100644 --- a/lib/puppet-strings/markdown/templates/data_type.erb +++ b/lib/puppet-strings/markdown/templates/data_type.erb @@ -43,6 +43,10 @@ ``` <% end -%> +<% end -%> +<% if alias_of -%> +Alias of `<%= alias_of %>` + <% end -%> <% if params -%> #### Parameters diff --git a/lib/puppet-strings/yard.rb b/lib/puppet-strings/yard.rb index 5a6313e6d..56ea11145 100644 --- a/lib/puppet-strings/yard.rb +++ b/lib/puppet-strings/yard.rb @@ -47,6 +47,7 @@ def all_objects :class, :puppet_class, :puppet_data_type, + :puppet_data_type_alias, :puppet_defined_type, :puppet_type, :puppet_provider, @@ -69,6 +70,10 @@ 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 diff --git a/lib/puppet-strings/yard/code_objects.rb b/lib/puppet-strings/yard/code_objects.rb index 024b548ce..f4f6f92b9 100644 --- a/lib/puppet-strings/yard/code_objects.rb +++ b/lib/puppet-strings/yard/code_objects.rb @@ -2,6 +2,7 @@ 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' diff --git a/lib/puppet-strings/yard/code_objects/data_type_alias.rb b/lib/puppet-strings/yard/code_objects/data_type_alias.rb new file mode 100644 index 000000000..324145628 --- /dev/null +++ b/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 diff --git a/lib/puppet-strings/yard/handlers.rb b/lib/puppet-strings/yard/handlers.rb index eb11168b0..705dcd48e 100644 --- a/lib/puppet-strings/yard/handlers.rb +++ b/lib/puppet-strings/yard/handlers.rb @@ -18,6 +18,7 @@ module JSON # The module for custom Puppet YARD handlers. module Puppet require 'puppet-strings/yard/handlers/puppet/class_handler' + require 'puppet-strings/yard/handlers/puppet/data_type_alias_handler' require 'puppet-strings/yard/handlers/puppet/defined_type_handler' require 'puppet-strings/yard/handlers/puppet/function_handler' require 'puppet-strings/yard/handlers/puppet/plan_handler' diff --git a/lib/puppet-strings/yard/handlers/puppet/data_type_alias_handler.rb b/lib/puppet-strings/yard/handlers/puppet/data_type_alias_handler.rb new file mode 100644 index 000000000..39eb9a6ad --- /dev/null +++ b/lib/puppet-strings/yard/handlers/puppet/data_type_alias_handler.rb @@ -0,0 +1,24 @@ +require 'puppet-strings/yard/handlers/helpers' +require 'puppet-strings/yard/handlers/puppet/base' +require 'puppet-strings/yard/parsers' +require 'puppet-strings/yard/code_objects' + +# Implements the handler for Puppet Data Type Alias. +class PuppetStrings::Yard::Handlers::Puppet::DataTypeAliasHandler < PuppetStrings::Yard::Handlers::Puppet::Base + handles PuppetStrings::Yard::Parsers::Puppet::DataTypeAliasStatement + + process do + # Register the object + object = PuppetStrings::Yard::CodeObjects::DataTypeAlias.new(statement) + register object + + # Log a warning if missing documentation + log.warn "Missing documentation for Puppet type alias '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty? + + # Mark the class as public if it doesn't already have an api tag + object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api + + # Warn if a summary longer than 140 characters was provided + PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary + end +end diff --git a/lib/puppet-strings/yard/parsers/puppet/parser.rb b/lib/puppet-strings/yard/parsers/puppet/parser.rb index 819057d2f..13a20cf16 100644 --- a/lib/puppet-strings/yard/parsers/puppet/parser.rb +++ b/lib/puppet-strings/yard/parsers/puppet/parser.rb @@ -76,6 +76,12 @@ def transform_PlanDefinition(o) # rubocop:disable Naming/UncommunicativeMethodPa statement end + def transform_TypeAlias(o) # rubocop:disable Naming/UncommunicativeMethodParamName + statement = PuppetStrings::Yard::Parsers::Puppet::DataTypeAliasStatement.new(o, @file) + statement.extract_docstring(@lines) + statement + end + def transform_Object(o) # rubocop:disable Naming/UncommunicativeMethodParamName # Ignore anything else (will be compacted out of the resulting array) end diff --git a/lib/puppet-strings/yard/parsers/puppet/statement.rb b/lib/puppet-strings/yard/parsers/puppet/statement.rb index eea04a744..e5233229c 100644 --- a/lib/puppet-strings/yard/parsers/puppet/statement.rb +++ b/lib/puppet-strings/yard/parsers/puppet/statement.rb @@ -165,4 +165,29 @@ def initialize(object, file) end end + # Implements the Puppet data type alias statement. + class DataTypeAliasStatement < Statement + attr_reader :name + attr_reader :alias_of + + # Initializes the Puppet data type alias statement. + # @param [Puppet::Pops::Model::TypeAlias] object The model object for the type statement. + # @param [String] file The file containing the statement. + def initialize(object, file) + super(object, file) + + type_expr = object.type_expr + case type_expr + when Puppet::Pops::Model::AccessExpression + # TODO: I don't like rebuilding the source from the AST, but AccessExpressions don't expose the original source + @alias_of = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(type_expr.left_expr).extract_text + '[' + @alias_of << type_expr.keys.map { |key| ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(key).extract_text }.join(', ') + @alias_of << ']' + else + adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(type_expr) + @alias_of = adapter.extract_text + end + @name = object.name + end + end end diff --git a/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_data_type.erb b/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_data_type.erb index 7eeb64eb0..3e253da81 100644 --- a/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_data_type.erb +++ b/lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_data_type.erb @@ -3,6 +3,7 @@
  • <%= linkify item, h(item.name(false)) %> + <% if item.type == :puppet_data_type_alias %>Alias<% end %>
    • <% even = !even %> diff --git a/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb b/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb index 9f006c6be..4087e9d9c 100644 --- a/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb +++ b/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb @@ -10,7 +10,7 @@ def generate_puppet_class_list # Generates the searchable Puppet data type list. # @return [void] def generate_puppet_data_type_list - @items = Registry.all(:puppet_data_type).sort_by {|dt| dt.name.to_s } + @items = Registry.all(:puppet_data_type, :puppet_data_type_alias).sort_by {|dt| dt.name.to_s } @list_title = 'Data Type List' @list_type = 'puppet_data_type' generate_list_contents diff --git a/lib/puppet-strings/yard/templates/default/layout/html/objects.erb b/lib/puppet-strings/yard/templates/default/layout/html/objects.erb index afc6356d7..d9d90732e 100644 --- a/lib/puppet-strings/yard/templates/default/layout/html/objects.erb +++ b/lib/puppet-strings/yard/templates/default/layout/html/objects.erb @@ -23,6 +23,8 @@ (Resource type: <%= obj.type_name %>) <% elsif obj.type == :puppet_function %> (<%= obj.function_type %>) + <% elsif obj.type == :puppet_data_type_alias %> + (Alias) <% end %> <% end %> diff --git a/lib/puppet-strings/yard/templates/default/layout/html/setup.rb b/lib/puppet-strings/yard/templates/default/layout/html/setup.rb index ebe760bdb..0750fce36 100644 --- a/lib/puppet-strings/yard/templates/default/layout/html/setup.rb +++ b/lib/puppet-strings/yard/templates/default/layout/html/setup.rb @@ -30,7 +30,7 @@ def layout @nav_url = url_for_list('puppet_class') @page_title = "Puppet Class: #{object.name}" @path = object.path - when PuppetStrings::Yard::CodeObjects::DataType + when PuppetStrings::Yard::CodeObjects::DataType, PuppetStrings::Yard::CodeObjects::DataTypeAlias @nav_url = url_for_list('puppet_data_type') @page_title = "Data Type: #{object.name}" @path = object.path @@ -168,7 +168,7 @@ def classes # @return [String] Returns the rendered section. def data_types @title = 'Data Type Listing A-Z' - @objects_by_letter = objects_by_letter(:puppet_data_type) + @objects_by_letter = objects_by_letter(:puppet_data_type, :puppet_data_type_alias) erb(:objects) end diff --git a/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/alias_of.erb b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/alias_of.erb new file mode 100644 index 000000000..956f1ab01 --- /dev/null +++ b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/alias_of.erb @@ -0,0 +1,10 @@ +<% if @alias_of && !@alias_of.empty? %> +
    +

    <%= @tag_title %>

    +
    +
    + 
    <%= @alias_of %>
    +
    +
    +
    +<% end %> diff --git a/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/box_info.erb b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/box_info.erb new file mode 100644 index 000000000..49a646067 --- /dev/null +++ b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/box_info.erb @@ -0,0 +1,10 @@ +
    +
    +
    Defined in:
    +
    + <%= object.file %><% if object.files.size > 1 %>,
    + <%= object.files[1..-1].map {|f| f.first }.join(",
    ") %>
    + <% end %> + + + diff --git a/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/header.erb b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/header.erb new file mode 100644 index 000000000..1929e8d92 --- /dev/null +++ b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/header.erb @@ -0,0 +1 @@ +

    Puppet Data Type Alias: <%= object.name %>

    diff --git a/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/note.erb b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/note.erb new file mode 100644 index 000000000..88c9ffb1e --- /dev/null +++ b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/note.erb @@ -0,0 +1,6 @@ +<% object.tags(:note).each do |tag| %> +
    + Note: + <%= htmlify_line tag.text %> +
    +<% end %> diff --git a/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/overview.erb b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/overview.erb new file mode 100644 index 000000000..a5b527a30 --- /dev/null +++ b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/overview.erb @@ -0,0 +1,6 @@ +

    Overview

    +
    +
    + <%= htmlify(object.docstring) %> +
    +
    diff --git a/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/setup.rb b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/setup.rb new file mode 100644 index 000000000..14d9d9002 --- /dev/null +++ b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/setup.rb @@ -0,0 +1,17 @@ +# Initializes the template. +# @return [void] +def init + sections :header, :box_info, :summary, :overview, :alias_of, :note, :todo, T('tags'), :source +end + +# Renders the alias_of section. +# @return [String] Returns the rendered section. +def alias_of + # Properties are the same thing as parameters (from the documentation standpoint), + # so reuse the same template but with a different title and data source. + #@parameters = object.properties || [] + #@parameters.sort_by! { |p| p.name } + @tag_title = 'Alias of' + @alias_of = object.alias_of + erb(:alias_of) +end diff --git a/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/source.erb b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/source.erb new file mode 100644 index 000000000..0fd3c5e35 --- /dev/null +++ b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/source.erb @@ -0,0 +1,12 @@ +
    + + + + + +
    + 
    <%= "\n\n\n" %><%= h format_lines(object) %>
    +     		+ 
    # File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %><%= "\n\n" %><%= html_syntax_highlight object.source %>
    +
    +
    diff --git a/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/summary.erb b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/summary.erb new file mode 100644 index 000000000..75e98677a --- /dev/null +++ b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/summary.erb @@ -0,0 +1,4 @@ +<% if object.docstring.has_tag?(:summary) %> +

    Summary

    + <%= object.docstring.tag(:summary).text %> +<% end %> diff --git a/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/todo.erb b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/todo.erb new file mode 100644 index 000000000..8f91636fb --- /dev/null +++ b/lib/puppet-strings/yard/templates/default/puppet_data_type_alias/html/todo.erb @@ -0,0 +1,6 @@ +<% object.tags(:todo).each do |tag| %> +
    + TODO: + <%= htmlify_line tag.text %> +
    +<% end %> diff --git a/spec/fixtures/unit/markdown/output_with_data_types.md b/spec/fixtures/unit/markdown/output_with_data_types.md index 511aa7b81..e53416f96 100644 --- a/spec/fixtures/unit/markdown/output_with_data_types.md +++ b/spec/fixtures/unit/markdown/output_with_data_types.md @@ -31,6 +31,8 @@ _Private Classes_ **Data types** +* [`Amodule::ComplexAlias`](#amodulecomplexalias): Documentation for Amodule::ComplexAlias +* [`Amodule::SimpleAlias`](#amodulesimplealias): Documentation for Amodule::SimpleAlias * [`UnitDataType`](#unitdatatype): An example Puppet Data Type in Ruby. **Tasks** @@ -478,6 +480,21 @@ The first parameter. ## Data types +### Amodule::ComplexAlias + +Documentation for Amodule::ComplexAlias + +Alias of `Struct[{ + value_type => Optional[ValueType], + merge => Optional[MergeType] +}]` + +### Amodule::SimpleAlias + +Documentation for Amodule::SimpleAlias + +Alias of `Variant[Numeric, String[1,20]]` + ### UnitDataType An example Puppet Data Type in Ruby. diff --git a/spec/unit/puppet-strings/markdown_spec.rb b/spec/unit/puppet-strings/markdown_spec.rb index a676c3b5f..8510f4528 100644 --- a/spec/unit/puppet-strings/markdown_spec.rb +++ b/spec/unit/puppet-strings/markdown_spec.rb @@ -293,6 +293,17 @@ def parse_data_type_content PUPPET end SOURCE + + YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) +# Documentation for Amodule::SimpleAlias +type Amodule::SimpleAlias = Variant[Numeric,String[1,20]] + +# Documentation for Amodule::ComplexAlias +type Amodule::ComplexAlias = Struct[{ + value_type => Optional[ValueType], + merge => Optional[MergeType] +}] + SOURCE end let(:baseline_path) { File.join(File.dirname(__FILE__), "../../fixtures/unit/markdown/#{filename}") } let(:baseline) { File.read(baseline_path) } diff --git a/spec/unit/puppet-strings/yard/handlers/puppet/data_type_alias_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/puppet/data_type_alias_handler_spec.rb new file mode 100644 index 000000000..07da863f1 --- /dev/null +++ b/spec/unit/puppet-strings/yard/handlers/puppet/data_type_alias_handler_spec.rb @@ -0,0 +1,65 @@ +require 'spec_helper' +require 'puppet-strings/yard' + +describe PuppetStrings::Yard::Handlers::Puppet::DataTypeAliasHandler, if: TEST_PUPPET_DATATYPES do + subject { + YARD::Parser::SourceParser.parse_string(source, :puppet) + YARD::Registry.all(:puppet_data_type_alias) + } + + describe 'parsing source without a type alias definition' do + let(:source) { 'notice hi' } + + it 'no aliases should be in the registry' do + expect(subject.empty?).to eq(true) + end + end + + describe 'parsing source with a syntax error' do + let(:source) { 'type Testype =' } + + it 'should log an error' do + expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of (file|input)/).to_stdout_from_any_process + expect(subject.empty?).to eq(true) + end + end + + describe 'parsing a data type alias with a missing docstring' do + let(:source) { 'type Testype = String[1]' } + + it 'should log a warning' do + expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet type alias 'Testype' at \(stdin\):1\./).to_stdout_from_any_process + end + end + + describe 'parsing a data type alias with a summary' do + context 'when the summary has fewer than 140 characters' do + let(:source) { <<-SOURCE + # A simple foo type. + # @summary A short summary. + type Testype = String[1] + SOURCE + } + + it 'should parse the summary' do + expect{ subject }.to output('').to_stdout_from_any_process + expect(subject.size).to eq(1) + summary = subject.first.tags(:summary) + expect(summary.first.text).to eq('A short summary.') + end + end + + context 'when the summary has more than 140 characters' do + let(:source) { <<-SOURCE + # A simple foo type. + # @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!! + type Testype = String[1] + SOURCE + } + + it 'should log a warning' do + expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_data_type_alias 'Testype' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process + end + end + end +end diff --git a/spec/unit/puppet-strings/yard/parsers/puppet/parser_spec.rb b/spec/unit/puppet-strings/yard/parsers/puppet/parser_spec.rb index f0ddb0152..1e83314f9 100644 --- a/spec/unit/puppet-strings/yard/parsers/puppet/parser_spec.rb +++ b/spec/unit/puppet-strings/yard/parsers/puppet/parser_spec.rb @@ -206,4 +206,46 @@ class bar { expect(statement.type).to eq("Struct\[{'a' => Integer[1, 10]}\]") end end + + describe 'parsing type alias definitions', if: TEST_PUPPET_DATATYPES do + context 'given a type alias on a single line' do + let(:source) { <<-SOURCE +# A simple foo type. +type Module::Typename = Variant[Stdlib::Windowspath, Stdlib::Unixpath] +SOURCE + } + + it 'should parse the puppet type statement' do + subject.parse + expect(subject.enumerator.size).to eq(1) + statement = subject.enumerator.first + expect(statement).to be_a(PuppetStrings::Yard::Parsers::Puppet::DataTypeAliasStatement) + expect(statement.docstring).to eq('A simple foo type.') + expect(statement.name).to eq('Module::Typename') + expect(statement.alias_of).to eq('Variant[Stdlib::Windowspath, Stdlib::Unixpath]') + end + end + + context 'given a type alias over multiple lines' do + let(:source) { <<-SOURCE +# A multiline foo type +# with long docs +type OptionsWithoutName = Struct[{ + value_type => Optional[ValueType], + merge => Optional[MergeType] +}] +SOURCE + } + + it 'should parse the puppet type statement' do + subject.parse + expect(subject.enumerator.size).to eq(1) + statement = subject.enumerator.first + expect(statement).to be_a(PuppetStrings::Yard::Parsers::Puppet::DataTypeAliasStatement) + expect(statement.docstring).to eq("A multiline foo type\nwith long docs") + expect(statement.name).to eq('OptionsWithoutName') + expect(statement.alias_of).to eq("Struct[{\n value_type => Optional[ValueType],\n merge => Optional[MergeType]\n}]") + end + end + end end