kienan
/
puppet-strings
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #119 from whopper/PDOC-125/master/overload_refactor 

(PDOC-125) Display all puppet function signatures in top-level signature key
This commit is contained in:
Jesse Scott 2016-11-14 14:16:06 -08:00 committed by GitHub
parent 70d5b1ccd7 f8c5628b66
commit 6c35f889d4
8 changed files with 574 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

165
JSON.md
View File

@ -115,22 +115,37 @@ 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). |
| 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",
"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",
"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": [

25
lib/puppet-strings/json.rb
View File

@ -25,15 +25,12 @@ module PuppetStrings::Json
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.
# @return [Hash] Returns a hash representation of the given docstring.
def self.docstring_to_hash(docstring)
hash = {}
hash[:text] = docstring
if docstring.is_a? YARD::Docstring
# 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 = docstring.tags.select { |t| t.tag_name != 'api' || t.text != 'public' }.map do |t|
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 }
@ -42,6 +39,18 @@ module PuppetStrings::Json
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, select_tags=nil)
hash = {}
hash[:text] = docstring
if docstring.is_a? YARD::Docstring
tags = tags_to_hashes(docstring.tags.select { |t| select_tags.nil? || select_tags.include?(t.tag_name.to_sym) })
hash[:tags] = tags unless tags.empty?
end
hash

16
lib/puppet-strings/yard/code_objects/function.rb
View File

@ -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?

2
lib/puppet-strings/yard/tags/overload_tag.rb
View File

@ -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

2
lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb
View File

@ -1,5 +1,5 @@
<% if object.has_tag?(:overload) && object.tags(:overload).any? {|o| !o.docstring.blank? } %>
<p class="tag_title">Overloads:</p>
<p class="tag_title">Signatures:</p>
<ul class="overload">
<% object.tags(:overload).each_with_index do |overload, index| %>
<% next if overload.docstring.blank? %>

200
spec/fixtures/unit/json/output.json vendored
View File

@ -84,7 +84,7 @@
{
"name": "database",
"file": "(stdin)",
"line": 45,
"line": 54,
"docstring": {
"text": "An example database server resource type."
},
@ -154,7 +154,7 @@
"name": "linux",
"type_name": "database",
"file": "(stdin)",
"line": 34,
"line": 43,
"docstring": {
"text": "An example provider on Linux."
},
@ -195,7 +195,47 @@
"file": "(stdin)",
"line": 6,
"type": "puppet",
"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": [
@ -242,7 +282,39 @@
"file": "(stdin)",
"line": 1,
"type": "ruby3x",
"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": [
@ -278,6 +350,78 @@
"file": "(stdin)",
"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": "",
"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": [
@ -358,6 +502,58 @@
]
},
"source": "Puppet::Functions.create_function(:func4x) do\n # The first overload.\n # @param param1 The first parameter.\n # @param param2 The second parameter.\n # @param param3 The third parameter.\n # @return Returns nothing.\n dispatch :foo do\n param 'Integer', :param1\n param 'Any', :param2\n optional_param 'Array[String]', :param3\n return_type 'Undef'\n end\n\n # @param param The first parameter.\n # @param block The block parameter.\n # @return Returns a string.\n dispatch :other do\n param 'Boolean', :param\n block_param\n return_type 'String'\n end\nend"
},
{
"name": "func4x_1",
"file": "(stdin)",
"line": 35,
"type": "ruby4x",
"signatures": [
{
"signature": "func4x_1(Integer $param1)",
"docstring": {
"text": "An example 4.x function with only one signature.",
"tags": [
{
"tag_name": "param",
"text": "The first parameter.",
"types": [
"Integer"
],
"name": "param1"
},
{
"tag_name": "return",
"text": "Returns nothing.",
"types": [
"Undef"
]
}
]
}
}
],
"docstring": {
"text": "An example 4.x function with only one signature.",
"tags": [
{
"tag_name": "param",
"text": "The first parameter.",
"types": [
"Integer"
],
"name": "param1"
},
{
"tag_name": "return",
"text": "Returns nothing.",
"types": [
"Undef"
]
}
]
},
"source": "Puppet::Functions.create_function(:func4x_1) do\n # @param param1 The first parameter.\n # @return [Undef] Returns nothing.\n dispatch :foobarbaz do\n param 'Integer', :param1\n end\nend"
}
]
}

160
spec/fixtures/unit/json/output_without_puppet_function.json vendored
View File

@ -84,7 +84,7 @@
{
"name": "database",
"file": "(stdin)",
"line": 45,
"line": 54,
"docstring": {
"text": "An example database server resource type."
},
@ -154,7 +154,7 @@
"name": "linux",
"type_name": "database",
"file": "(stdin)",
"line": 34,
"line": 43,
"docstring": {
"text": "An example provider on Linux."
},
@ -195,7 +195,39 @@
"file": "(stdin)",
"line": 1,
"type": "ruby3x",
"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": [
@ -231,6 +263,78 @@
"file": "(stdin)",
"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": "",
"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": [
@ -311,6 +415,58 @@
]
},
"source": "Puppet::Functions.create_function(:func4x) do\n # The first overload.\n # @param param1 The first parameter.\n # @param param2 The second parameter.\n # @param param3 The third parameter.\n # @return Returns nothing.\n dispatch :foo do\n param 'Integer', :param1\n param 'Any', :param2\n optional_param 'Array[String]', :param3\n return_type 'Undef'\n end\n\n # @param param The first parameter.\n # @param block The block parameter.\n # @return Returns a string.\n dispatch :other do\n param 'Boolean', :param\n block_param\n return_type 'String'\n end\nend"
},
{
"name": "func4x_1",
"file": "(stdin)",
"line": 35,
"type": "ruby4x",
"signatures": [
{
"signature": "func4x_1(Integer $param1)",
"docstring": {
"text": "An example 4.x function with only one signature.",
"tags": [
{
"tag_name": "param",
"text": "The first parameter.",
"types": [
"Integer"
],
"name": "param1"
},
{
"tag_name": "return",
"text": "Returns nothing.",
"types": [
"Undef"
]
}
]
}
}
],
"docstring": {
"text": "An example 4.x function with only one signature.",
"tags": [
{
"tag_name": "param",
"text": "The first parameter.",
"types": [
"Integer"
],
"name": "param1"
},
{
"tag_name": "return",
"text": "Returns nothing.",
"types": [
"Undef"
]
}
]
},
"source": "Puppet::Functions.create_function(:func4x_1) do\n # @param param1 The first parameter.\n # @return [Undef] Returns nothing.\n dispatch :foobarbaz do\n param 'Integer', :param1\n end\nend"
}
]
}

9
spec/unit/puppet-strings/json_spec.rb
View File

@ -66,6 +66,15 @@ Puppet::Functions.create_function(:func4x) do
end
end
# An example 4.x function with only one signature.
Puppet::Functions.create_function(:func4x_1) do
# @param param1 The first parameter.
# @return [Undef] Returns nothing.
dispatch :foobarbaz do
param 'Integer', :param1
end
end
Puppet::Type.type(:database).provide :linux do
desc 'An example provider on Linux.'
confine kernel: 'Linux'