diff --git a/JSON.md b/JSON.md index 805c88e..f88f7a3 100644 --- a/JSON.md +++ b/JSON.md @@ -114,23 +114,38 @@ Puppet Functions Each entry in the `puppet_functions` list is an object with the following attributes: -| Attribute Key | Description | -| ------------- | ---------------------------------------------------- | -| name | The name of the function. | -| file | The file defining the provider. | -| line | The line where the provider is defined. | -| type | The function type (e.g. ruby3x, ruby4x, puppet). | -| signature | The Puppet signature of the function (no overloads). | -| docstring | The *DocString* object for the function (see below). | -| defaults | The map of parameter names to default values. | -| source | The source code for the function. | +| Attribute Key | Description | +| ------------- | ----------------------------------------------------------------------------- | +| name | The name of the function. | +| file | The file defining the provider. | +| line | The line where the provider is defined. | +| type | The function type (e.g. ruby3x, ruby4x, puppet). | +| signatures | A list of Puppet signatures of the function, including overloads if present. | +| docstring | The *DocString* object for the function (see below). | +| defaults | The map of parameter names to default values. | +| source | The source code for the function. | + +Signature Objects +----------------- + +The `signatures` key is a function-specific list containing an object for each signature of a +function. Each object includes the `signature` itself, as well as each of its `param` and `return` +tags. Puppet 4.x functions with overloads will contain multiple signatures, while other function +types will contain only one. + +Each signature is represented as an object with the following attributes: + +| Attribute Key | Description | +| ------------- | -------------------------------------------------------------------------------------------------- | +| signature | The signature of the function. | +| docstring | The *DocString* object describing the signature, which includes `text`, `param` and `return` tags. | DocString Objects ----------------- For the above types, their docstrings are represented as an object with the following attributes: -| Attribute Key | Description DocString | +| Attribute Key | Description | | ------------- | --------------------------------------------------- | | text | The textual part of the DocString. | | tags | The array of tag objects, if any are present. | @@ -356,7 +371,47 @@ An example JSON document describing a Puppet class, defined type, resource type, "file": "site.pp", "line": 20, "type": "puppet", - "signature": "func(Integer $param1, Any $param2, String $param3 = hi)", + "signatures": [ + { + "signature": "func(Integer $param1, Any $param2, String $param3 = hi)", + "docstring": { + "text": "A simple function.", + "tags": [ + { + "tag_name": "param", + "text": "First param.", + "types": [ + "Integer" + ], + "name": "param1" + }, + { + "tag_name": "param", + "text": "Second param.", + "types": [ + "Any" + ], + "name": "param2" + }, + { + "tag_name": "param", + "text": "Third param.", + "types": [ + "String" + ], + "name": "param3" + }, + { + "tag_name": "return", + "text": "Returns nothing.", + "types": [ + "Undef" + ] + } + ] + } + } + ], "docstring": { "text": "A simple function.", "tags": [ @@ -403,7 +458,39 @@ An example JSON document describing a Puppet class, defined type, resource type, "file": "func3x.rb", "line": 1, "type": "ruby3x", - "signature": "func3x(String $first, Any $second)", + "signatures": [ + { + "signature": "func3x(String $first, Any $second)", + "docstring": { + "text": "An example 3.x function.", + "tags": [ + { + "tag_name": "param", + "text": "The first parameter.", + "types": [ + "String" + ], + "name": "first" + }, + { + "tag_name": "param", + "text": "The second parameter.", + "types": [ + "Any" + ], + "name": "second" + }, + { + "tag_name": "return", + "text": "Returns nothing.", + "types": [ + "Undef" + ] + } + ] + } + } + ], "docstring": { "text": "An example 3.x function.", "tags": [ @@ -439,6 +526,78 @@ An example JSON document describing a Puppet class, defined type, resource type, "file": "func4x.rb", "line": 11, "type": "ruby4x", + "signatures": [ + { + "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)", + "docstring": { + "text": "The first overload.", + "tags": [ + { + "tag_name": "param", + "text": "The first parameter.", + "types": [ + "Integer" + ], + "name": "param1" + }, + { + "tag_name": "param", + "text": "The second parameter.", + "types": [ + "Any" + ], + "name": "param2" + }, + { + "tag_name": "param", + "text": "The third parameter.", + "types": [ + "Optional[Array[String]]" + ], + "name": "param3" + }, + { + "tag_name": "return", + "text": "Returns nothing.", + "types": [ + "Undef" + ] + } + ] + } + }, + { + "signature": "func4x(Boolean $param, Callable &$block)", + "docstring": { + "text": "The second overload.", + "tags": [ + { + "tag_name": "param", + "text": "The first parameter.", + "types": [ + "Boolean" + ], + "name": "param" + }, + { + "tag_name": "param", + "text": "The block parameter.", + "types": [ + "Callable" + ], + "name": "&block" + }, + { + "tag_name": "return", + "text": "Returns a string.", + "types": [ + "String" + ] + } + ] + } + } + ], "docstring": { "text": "An example 4.x function.", "tags": [ diff --git a/lib/puppet-strings/json.rb b/lib/puppet-strings/json.rb index d6d2e42..ae433c1 100644 --- a/lib/puppet-strings/json.rb +++ b/lib/puppet-strings/json.rb @@ -25,23 +25,32 @@ module PuppetStrings::Json end end + # Converts a list of tags into an array of hashes. + # @param [Array] tags List of tags to be converted into an array of hashes. + # @return [Array] Returns an array of tag hashes. + def self.tags_to_hashes(tags) + # Skip over the API tags that are public + tags.select { |t| (t.tag_name != 'api' || t.text != 'public') }.map do |t| + next t.to_hash if t.respond_to?(:to_hash) + + tag = { tag_name: t.tag_name } + tag[:text] = t.text if t.text + tag[:types] = t.types if t.types + tag[:name] = t.name if t.name + tag + end + end + # Converts a YARD::Docstring (or String) to a docstring hash for JSON output. # @param [YARD::Docstring, String] docstring The docstring to convert to a hash. + # @param [Array] select_tags List of tags to select. Other tags will be filtered out. # @return [Hash] Returns a hash representation of the given docstring. - def self.docstring_to_hash(docstring) + def self.docstring_to_hash(docstring, select_tags=nil) hash = {} hash[:text] = docstring if docstring.is_a? YARD::Docstring - # Skip over the API tags that are public - tags = docstring.tags.select { |t| t.tag_name != 'api' || t.text != 'public' }.map do |t| - next t.to_hash if t.respond_to?(:to_hash) + tags = tags_to_hashes(docstring.tags.select { |t| select_tags.nil? || select_tags.include?(t.tag_name.to_sym) }) - tag = { tag_name: t.tag_name } - tag[:text] = t.text if t.text - tag[:types] = t.types if t.types - tag[:name] = t.name if t.name - tag - end hash[:tags] = tags unless tags.empty? end hash diff --git a/lib/puppet-strings/yard/code_objects/function.rb b/lib/puppet-strings/yard/code_objects/function.rb index f295d29..4c2edf2 100644 --- a/lib/puppet-strings/yard/code_objects/function.rb +++ b/lib/puppet-strings/yard/code_objects/function.rb @@ -64,7 +64,7 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje tags = self.tags(:param) args = @parameters.map do |parameter| name, default = parameter - tag = tags.find { |tag| tag.name == name } if tags + tag = tags.find { |t| t.name == name } if tags type = tag && tag.types ? "#{tag.type} " : 'Any ' prefix = "#{name[0]}" if name.start_with?('*', '&') name = name[1..-1] if prefix @@ -78,12 +78,22 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje # @return [Hash] Returns a hash representation of the code object. def to_hash hash = {} + hash[:name] = name hash[:file] = file hash[:line] = line hash[:type] = @function_type.to_s - signature = self.signature - hash[:signature] = signature unless signature.empty? + hash[:signatures] = [] + + if self.has_tag? :overload + # loop over overloads and append onto the signatures array + self.tags(:overload).each do |o| + hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Json.docstring_to_hash(o.docstring, [:param, :return]) } + end + else + hash[:signatures] << { :signature => self.signature, :docstring => PuppetStrings::Json.docstring_to_hash(docstring, [:param, :return]) } + end + hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten] hash[:defaults] = defaults unless defaults.empty? diff --git a/lib/puppet-strings/yard/tags/overload_tag.rb b/lib/puppet-strings/yard/tags/overload_tag.rb index e7557f7..9bbb684 100644 --- a/lib/puppet-strings/yard/tags/overload_tag.rb +++ b/lib/puppet-strings/yard/tags/overload_tag.rb @@ -21,7 +21,7 @@ class PuppetStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag tags = self.tags(:param) args = @parameters.map do |parameter| name, default = parameter - tag = tags.find { |tag| tag.name == name } if tags + tag = tags.find { |t| t.name == name } if tags type = tag && tag.types ? "#{tag.type} " : 'Any ' prefix = "#{name[0]}" if name.start_with?('*', '&') name = name[1..-1] if prefix diff --git a/lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb b/lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb index 3d12d59..93add67 100644 --- a/lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb +++ b/lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb @@ -1,5 +1,5 @@ <% if object.has_tag?(:overload) && object.tags(:overload).any? {|o| !o.docstring.blank? } %> -

Overloads:

+

Signatures: