puppet-strings 0.99.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +23 -0
- data/Gemfile +7 -6
- data/JSON.md +193 -20
- data/README.md +231 -140
- data/lib/puppet-strings/json.rb +19 -10
- data/lib/puppet-strings/tasks/gh_pages.rb +15 -4
- data/lib/puppet-strings/yard/code_objects/function.rb +13 -3
- data/lib/puppet-strings/yard/code_objects/provider.rb +5 -6
- data/lib/puppet-strings/yard/code_objects/type.rb +2 -1
- data/lib/puppet-strings/yard/handlers/puppet/function_handler.rb +9 -4
- data/lib/puppet-strings/yard/handlers/ruby/function_handler.rb +13 -4
- data/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb +11 -6
- data/lib/puppet-strings/yard/handlers/ruby/type_handler.rb +3 -3
- data/lib/puppet-strings/yard/parsers/puppet/statement.rb +8 -0
- data/lib/puppet-strings/yard/tags/overload_tag.rb +2 -2
- data/lib/puppet-strings/yard/templates/default/fulldoc/html/css/common.css +8 -0
- data/lib/puppet-strings/yard/templates/default/puppet_provider/html/collection.erb +9 -2
- data/lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb +1 -1
- data/lib/puppet-strings/yard/util.rb +17 -0
- data/spec/acceptance/emit_json_options.rb +15 -1
- data/spec/fixtures/unit/json/output.json +220 -9
- data/spec/fixtures/unit/json/output_without_puppet_function.json +179 -8
- data/spec/spec_helper.rb +3 -0
- data/spec/unit/puppet-strings/json_spec.rb +15 -4
- data/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb +72 -0
- data/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb +44 -0
- data/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb +20 -2
- data/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb +25 -1
- data/spec/unit/puppet-strings/yard/parsers/puppet/parser_spec.rb +38 -0
- data/spec/unit/puppet-strings/yard/util_spec.rb +31 -0
- metadata +5 -2
data/lib/puppet-strings/json.rb
CHANGED
@@ -25,23 +25,32 @@ module PuppetStrings::Json
|
|
25
25
|
end
|
26
26
|
end
|
27
27
|
|
28
|
+
# Converts a list of tags into an array of hashes.
|
29
|
+
# @param [Array] tags List of tags to be converted into an array of hashes.
|
30
|
+
# @return [Array] Returns an array of tag hashes.
|
31
|
+
def self.tags_to_hashes(tags)
|
32
|
+
# Skip over the API tags that are public
|
33
|
+
tags.select { |t| (t.tag_name != 'api' || t.text != 'public') }.map do |t|
|
34
|
+
next t.to_hash if t.respond_to?(:to_hash)
|
35
|
+
|
36
|
+
tag = { tag_name: t.tag_name }
|
37
|
+
tag[:text] = t.text if t.text
|
38
|
+
tag[:types] = t.types if t.types
|
39
|
+
tag[:name] = t.name if t.name
|
40
|
+
tag
|
41
|
+
end
|
42
|
+
end
|
43
|
+
|
28
44
|
# Converts a YARD::Docstring (or String) to a docstring hash for JSON output.
|
29
45
|
# @param [YARD::Docstring, String] docstring The docstring to convert to a hash.
|
46
|
+
# @param [Array] select_tags List of tags to select. Other tags will be filtered out.
|
30
47
|
# @return [Hash] Returns a hash representation of the given docstring.
|
31
|
-
def self.docstring_to_hash(docstring)
|
48
|
+
def self.docstring_to_hash(docstring, select_tags=nil)
|
32
49
|
hash = {}
|
33
50
|
hash[:text] = docstring
|
34
51
|
if docstring.is_a? YARD::Docstring
|
35
|
-
|
36
|
-
tags = docstring.tags.select { |t| t.tag_name != 'api' || t.text != 'public' }.map do |t|
|
37
|
-
next t.to_hash if t.respond_to?(:to_hash)
|
52
|
+
tags = tags_to_hashes(docstring.tags.select { |t| select_tags.nil? || select_tags.include?(t.tag_name.to_sym) })
|
38
53
|
|
39
|
-
tag = { tag_name: t.tag_name }
|
40
|
-
tag[:text] = t.text if t.text
|
41
|
-
tag[:types] = t.types if t.types
|
42
|
-
tag[:name] = t.name if t.name
|
43
|
-
tag
|
44
|
-
end
|
45
54
|
hash[:tags] = tags unless tags.empty?
|
46
55
|
end
|
47
56
|
hash
|
@@ -2,7 +2,6 @@ require 'puppet-strings/tasks'
|
|
2
2
|
|
3
3
|
namespace :strings do
|
4
4
|
namespace :gh_pages do
|
5
|
-
desc 'Checkout the gh-pages branch for doc generation.'
|
6
5
|
task :checkout do
|
7
6
|
if Dir.exist?('doc')
|
8
7
|
fail "The 'doc' directory (#{File.expand_path('doc')}) is not a Git repository! Remove it and run the Rake task again." unless Dir.exist?('doc/.git')
|
@@ -24,19 +23,31 @@ namespace :strings do
|
|
24
23
|
end
|
25
24
|
end
|
26
25
|
|
27
|
-
|
26
|
+
task :configure do
|
27
|
+
unless File.exist?(File.join('doc', '_config.yml'))
|
28
|
+
Dir.chdir('doc') do
|
29
|
+
File.open('_config.yml', 'w+') {|f| f.write("include: _index.html") }
|
30
|
+
end
|
31
|
+
end
|
32
|
+
end
|
33
|
+
|
28
34
|
task :push do
|
35
|
+
output = `git describe --long 2>/dev/null`
|
36
|
+
# If a project has never been tagged, fall back to latest SHA
|
37
|
+
output.empty? ? git_sha = `git log --pretty=format:'%H' -n 1` : git_sha = output
|
38
|
+
|
29
39
|
Dir.chdir('doc') do
|
30
40
|
system 'git add .'
|
31
|
-
system "git commit -m '[strings] Generated Documentation Update'"
|
41
|
+
system "git commit -m '[strings] Generated Documentation Update at Revision #{git_sha}'"
|
32
42
|
system 'git push origin gh-pages -f'
|
33
43
|
end
|
34
44
|
end
|
35
45
|
|
36
|
-
desc '
|
46
|
+
desc 'Update docs on the gh-pages branch and push to GitHub.'
|
37
47
|
task :update => [
|
38
48
|
:checkout,
|
39
49
|
:'strings:generate',
|
50
|
+
:configure,
|
40
51
|
:push,
|
41
52
|
]
|
42
53
|
end
|
@@ -64,7 +64,7 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
|
|
64
64
|
tags = self.tags(:param)
|
65
65
|
args = @parameters.map do |parameter|
|
66
66
|
name, default = parameter
|
67
|
-
tag = tags.find { |
|
67
|
+
tag = tags.find { |t| t.name == name } if tags
|
68
68
|
type = tag && tag.types ? "#{tag.type} " : 'Any '
|
69
69
|
prefix = "#{name[0]}" if name.start_with?('*', '&')
|
70
70
|
name = name[1..-1] if prefix
|
@@ -78,12 +78,22 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
|
|
78
78
|
# @return [Hash] Returns a hash representation of the code object.
|
79
79
|
def to_hash
|
80
80
|
hash = {}
|
81
|
+
|
81
82
|
hash[:name] = name
|
82
83
|
hash[:file] = file
|
83
84
|
hash[:line] = line
|
84
85
|
hash[:type] = @function_type.to_s
|
85
|
-
|
86
|
-
|
86
|
+
hash[:signatures] = []
|
87
|
+
|
88
|
+
if self.has_tag? :overload
|
89
|
+
# loop over overloads and append onto the signatures array
|
90
|
+
self.tags(:overload).each do |o|
|
91
|
+
hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Json.docstring_to_hash(o.docstring, [:param, :return]) }
|
92
|
+
end
|
93
|
+
else
|
94
|
+
hash[:signatures] << { :signature => self.signature, :docstring => PuppetStrings::Json.docstring_to_hash(docstring, [:param, :return]) }
|
95
|
+
end
|
96
|
+
|
87
97
|
hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
|
88
98
|
defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
|
89
99
|
hash[:defaults] = defaults unless defaults.empty?
|
@@ -56,13 +56,12 @@ class PuppetStrings::Yard::CodeObjects::Provider < PuppetStrings::Yard::CodeObje
|
|
56
56
|
end
|
57
57
|
|
58
58
|
# Adds a default to the provider.
|
59
|
-
# @param [
|
60
|
-
# @param [String] value The default's value.
|
59
|
+
# @param [Array] constraints List of related key-pair values for the default.
|
61
60
|
# @return [void]
|
62
|
-
def add_default(
|
63
|
-
return unless
|
64
|
-
@defaults ||=
|
65
|
-
@defaults
|
61
|
+
def add_default(constraints)
|
62
|
+
return unless constraints
|
63
|
+
@defaults ||= []
|
64
|
+
@defaults << constraints
|
66
65
|
end
|
67
66
|
|
68
67
|
# Adds a command to the provider.
|
@@ -1,4 +1,5 @@
|
|
1
1
|
require 'puppet-strings/yard/code_objects/group'
|
2
|
+
require 'puppet-strings/yard/util'
|
2
3
|
|
3
4
|
# Implements the group for Puppet resource types.
|
4
5
|
class PuppetStrings::Yard::CodeObjects::Types < PuppetStrings::Yard::CodeObjects::Group
|
@@ -78,7 +79,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
|
|
78
79
|
# @param [String] docstring The docstring of the feature.
|
79
80
|
def initialize(name, docstring)
|
80
81
|
@name = name
|
81
|
-
@docstring = docstring
|
82
|
+
@docstring = PuppetStrings::Yard::Util.scrub_string(docstring).gsub("\n", ' ')
|
82
83
|
end
|
83
84
|
|
84
85
|
# Converts the feature to a hash representation.
|
@@ -20,7 +20,7 @@ class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Ya
|
|
20
20
|
set_parameter_types(object)
|
21
21
|
|
22
22
|
# Add a return tag
|
23
|
-
add_return_tag(object)
|
23
|
+
add_return_tag(object, statement.type)
|
24
24
|
|
25
25
|
# Set the parameters on the object
|
26
26
|
object.parameters = statement.parameters.map { |p| [p.name, p.value] }
|
@@ -30,13 +30,18 @@ class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Ya
|
|
30
30
|
end
|
31
31
|
|
32
32
|
private
|
33
|
-
def add_return_tag(object)
|
33
|
+
def add_return_tag(object, type=nil)
|
34
34
|
tag = object.tag(:return)
|
35
35
|
if tag
|
36
|
-
tag.types
|
36
|
+
if (type && tag.types) && (type != tag.types)
|
37
|
+
log.warn "Documented return type does not match return type in function definition near #{statement.file}:#{statement.line}."
|
38
|
+
end
|
39
|
+
|
40
|
+
tag.types = type ? [type] : tag.types || ['Any']
|
37
41
|
return
|
38
42
|
end
|
39
43
|
log.warn "Missing @return tag near #{statement.file}:#{statement.line}."
|
40
|
-
|
44
|
+
type = type || 'Any'
|
45
|
+
object.add_tag YARD::Tags::Tag.new(:return, '', type)
|
41
46
|
end
|
42
47
|
end
|
@@ -1,6 +1,6 @@
|
|
1
1
|
require 'puppet-strings/yard/handlers/ruby/base'
|
2
2
|
require 'puppet-strings/yard/code_objects'
|
3
|
-
require 'puppet/util
|
3
|
+
require 'puppet-strings/yard/util'
|
4
4
|
|
5
5
|
# Implements the handler for Puppet functions written in Ruby.
|
6
6
|
class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard::Handlers::Ruby::Base
|
@@ -15,6 +15,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
|
|
15
15
|
block_param
|
16
16
|
required_block_param
|
17
17
|
optional_block_param
|
18
|
+
return_type
|
18
19
|
).freeze
|
19
20
|
|
20
21
|
namespace_only
|
@@ -23,12 +24,15 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
|
|
23
24
|
|
24
25
|
process do
|
25
26
|
# Only accept calls to Puppet::Functions (4.x) or Puppet::Parser::Functions (3.x)
|
27
|
+
# When `newfunction` is separated from the Puppet::Parser::Functions module name by a
|
28
|
+
# newline, YARD ignores the namespace and uses `newfunction` as the source of the
|
29
|
+
# first statement.
|
26
30
|
return unless statement.count > 1
|
27
31
|
module_name = statement[0].source
|
28
|
-
return unless module_name == 'Puppet::Functions' || module_name == 'Puppet::Parser::Functions'
|
32
|
+
return unless module_name == 'Puppet::Functions' || module_name == 'Puppet::Parser::Functions' || module_name == 'newfunction'
|
29
33
|
|
30
34
|
# Create and register the function object
|
31
|
-
is_3x = module_name == 'Puppet::Parser::Functions'
|
35
|
+
is_3x = module_name == 'Puppet::Parser::Functions' || module_name == 'newfunction'
|
32
36
|
object = PuppetStrings::Yard::CodeObjects::Function.new(
|
33
37
|
get_name,
|
34
38
|
is_3x ? PuppetStrings::Yard::CodeObjects::Function::RUBY_3X : PuppetStrings::Yard::CodeObjects::Function::RUBY_4X
|
@@ -130,6 +134,11 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
|
|
130
134
|
method_name = child.method_name.source
|
131
135
|
next unless DISPATCH_METHOD_NAMES.include?(method_name)
|
132
136
|
|
137
|
+
if method_name == 'return_type'
|
138
|
+
overload_tag.tag(:return).types = [node_as_string(child.parameters[0])]
|
139
|
+
next
|
140
|
+
end
|
141
|
+
|
133
142
|
# Check for block
|
134
143
|
if method_name.include?('block')
|
135
144
|
if block
|
@@ -335,7 +344,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
|
|
335
344
|
docstring = node_as_string(kvp[1])
|
336
345
|
|
337
346
|
log.error "Failed to parse docstring for 3.x Puppet function '#{name}' near #{statement.file}:#{statement.line}." and return nil unless docstring
|
338
|
-
return
|
347
|
+
return PuppetStrings::Yard::Util.scrub_string(docstring)
|
339
348
|
end
|
340
349
|
end
|
341
350
|
|
@@ -1,6 +1,6 @@
|
|
1
1
|
require 'puppet-strings/yard/handlers/ruby/base'
|
2
2
|
require 'puppet-strings/yard/code_objects'
|
3
|
-
require 'puppet/util
|
3
|
+
require 'puppet-strings/yard/util'
|
4
4
|
|
5
5
|
# Implements the handler for Puppet providers written in Ruby.
|
6
6
|
class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard::Handlers::Ruby::Base
|
@@ -53,7 +53,7 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
|
|
53
53
|
next unless ivar != child && ivar.source == '@doc'
|
54
54
|
docstring = node_as_string(child[1])
|
55
55
|
log.error "Failed to parse docstring for Puppet provider '#{object.name}' (resource type '#{object.type_name}') near #{child.file}:#{child.line}." and return nil unless docstring
|
56
|
-
register_docstring(object,
|
56
|
+
register_docstring(object, PuppetStrings::Yard::Util.scrub_string(docstring), nil)
|
57
57
|
return nil
|
58
58
|
elsif child.is_a?(YARD::Parser::Ruby::MethodCallNode)
|
59
59
|
# Look for a call to a dispatch method with a block
|
@@ -64,7 +64,7 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
|
|
64
64
|
|
65
65
|
docstring = node_as_string(child.parameters[0])
|
66
66
|
log.error "Failed to parse docstring for Puppet provider '#{object.name}' (resource type '#{object.type_name}') near #{child.file}:#{child.line}." and return nil unless docstring
|
67
|
-
register_docstring(object,
|
67
|
+
register_docstring(object, PuppetStrings::Yard::Util.scrub_string(docstring), nil)
|
68
68
|
return nil
|
69
69
|
end
|
70
70
|
end
|
@@ -96,9 +96,14 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
|
|
96
96
|
elsif method_name == 'defaultfor'
|
97
97
|
# Add a default to the object
|
98
98
|
next unless parameters.count >= 1
|
99
|
-
|
100
|
-
|
101
|
-
|
99
|
+
# Some defaultfor statements contain multiple constraints.
|
100
|
+
parameters.each do |kvps|
|
101
|
+
next unless kvps.count >= 1
|
102
|
+
defaultfor = []
|
103
|
+
kvps.each do |kvp|
|
104
|
+
defaultfor << [node_as_string(kvp[0]) || kvp[0].source, node_as_string(kvp[1]) || kvp[1].source]
|
105
|
+
end
|
106
|
+
object.add_default(defaultfor)
|
102
107
|
end
|
103
108
|
elsif method_name == 'commands'
|
104
109
|
# Add the commands to the object
|
@@ -1,6 +1,6 @@
|
|
1
1
|
require 'puppet-strings/yard/handlers/ruby/base'
|
2
2
|
require 'puppet-strings/yard/code_objects'
|
3
|
-
require 'puppet/util'
|
3
|
+
require 'puppet-strings/yard/util'
|
4
4
|
|
5
5
|
# Implements the handler for Puppet resource types written in Ruby.
|
6
6
|
class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Handlers::Ruby::Base
|
@@ -49,7 +49,7 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha
|
|
49
49
|
next unless ivar != child && ivar.source == '@doc'
|
50
50
|
docstring = node_as_string(child[1])
|
51
51
|
log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring
|
52
|
-
return
|
52
|
+
return PuppetStrings::Yard::Util.scrub_string(docstring)
|
53
53
|
elsif child.is_a?(YARD::Parser::Ruby::MethodCallNode)
|
54
54
|
# Look for a call to a dispatch method with a block
|
55
55
|
next unless child.method_name &&
|
@@ -58,7 +58,7 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha
|
|
58
58
|
|
59
59
|
docstring = node_as_string(child.parameters[0])
|
60
60
|
log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring
|
61
|
-
return
|
61
|
+
return PuppetStrings::Yard::Util.scrub_string(docstring)
|
62
62
|
end
|
63
63
|
end
|
64
64
|
log.warn "Missing a description for #{kind} at #{node.file}:#{node.line}."
|
@@ -134,6 +134,7 @@ module PuppetStrings::Yard::Parsers::Puppet
|
|
134
134
|
# Implements the Puppet function statement.
|
135
135
|
class FunctionStatement < ParameterizedStatement
|
136
136
|
attr_reader :name
|
137
|
+
attr_reader :type
|
137
138
|
|
138
139
|
# Initializes the Puppet function statement.
|
139
140
|
# @param [Puppet::Pops::Model::FunctionDefinition] object The model object for the function statement.
|
@@ -141,6 +142,13 @@ module PuppetStrings::Yard::Parsers::Puppet
|
|
141
142
|
def initialize(object, file)
|
142
143
|
super(object, file)
|
143
144
|
@name = object.name
|
145
|
+
if object.respond_to? :return_type
|
146
|
+
type = object.return_type
|
147
|
+
if type
|
148
|
+
adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(type)
|
149
|
+
@type = adapter.extract_text.gsub('>> ', '')
|
150
|
+
end
|
151
|
+
end
|
144
152
|
end
|
145
153
|
end
|
146
154
|
end
|
@@ -21,7 +21,7 @@ class PuppetStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag
|
|
21
21
|
tags = self.tags(:param)
|
22
22
|
args = @parameters.map do |parameter|
|
23
23
|
name, default = parameter
|
24
|
-
tag = tags.find { |
|
24
|
+
tag = tags.find { |t| t.name == name } if tags
|
25
25
|
type = tag && tag.types ? "#{tag.type} " : 'Any '
|
26
26
|
prefix = "#{name[0]}" if name.start_with?('*', '&')
|
27
27
|
name = name[1..-1] if prefix
|
@@ -99,7 +99,7 @@ class PuppetStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag
|
|
99
99
|
hash[:tag_name] = tag_name
|
100
100
|
hash[:text] = text if text
|
101
101
|
hash[:signature] = signature
|
102
|
-
hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) if !docstring.
|
102
|
+
hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) if !docstring.blank?
|
103
103
|
defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
|
104
104
|
hash[:defaults] = defaults unless defaults.empty?
|
105
105
|
hash[:types] = types if types
|
@@ -2,8 +2,15 @@
|
|
2
2
|
<div class="tags">
|
3
3
|
<p class="tag_title"><%= @title %></p>
|
4
4
|
<ul>
|
5
|
-
|
6
|
-
|
5
|
+
|
6
|
+
<% if @collection.is_a?(Hash) %>
|
7
|
+
<% @collection.each do |key, value| %>
|
8
|
+
<li><tt><%= key %> — <%= value %></tt></li>
|
9
|
+
<% end %>
|
10
|
+
<% elsif @collection.is_a?(Array) %>
|
11
|
+
<% @collection.each do |kvps| %>
|
12
|
+
<li><tt><%= kvps.map{|k,v| "#{k} — #{v}"}.join(', ') %></tt></li>
|
13
|
+
<% end %>
|
7
14
|
<% end %>
|
8
15
|
</ul>
|
9
16
|
</div>
|
@@ -1,5 +1,5 @@
|
|
1
1
|
<% if object.has_tag?(:overload) && object.tags(:overload).any? {|o| !o.docstring.blank? } %>
|
2
|
-
<p class="tag_title">
|
2
|
+
<p class="tag_title">Signatures:</p>
|
3
3
|
<ul class="overload">
|
4
4
|
<% object.tags(:overload).each_with_index do |overload, index| %>
|
5
5
|
<% next if overload.docstring.blank? %>
|
@@ -0,0 +1,17 @@
|
|
1
|
+
require 'puppet/util'
|
2
|
+
|
3
|
+
# The module for various puppet-strings utility helpers.
|
4
|
+
module PuppetStrings::Yard::Util
|
5
|
+
# Trims indentation from trailing whitespace and removes ruby literal quotation
|
6
|
+
# syntax `%Q{}` and `%{q}` from parsed strings.
|
7
|
+
# @param [String] str The string to scrub.
|
8
|
+
# @return [String] A scrubbed string.
|
9
|
+
def self.scrub_string(str)
|
10
|
+
match = str.match(/^%[Qq]{(.*)}$/m)
|
11
|
+
if match
|
12
|
+
return Puppet::Util::Docs.scrub(match[1])
|
13
|
+
end
|
14
|
+
|
15
|
+
Puppet::Util::Docs.scrub(str)
|
16
|
+
end
|
17
|
+
end
|
@@ -15,7 +15,21 @@ expected = {
|
|
15
15
|
"file" => "/etc/puppet/modules/test/lib/puppet/parser/functions/function3x.rb",
|
16
16
|
"line" => 1,
|
17
17
|
"type" => "ruby3x",
|
18
|
-
"
|
18
|
+
"signatures" => [
|
19
|
+
{
|
20
|
+
"signature" =>"function3x()",
|
21
|
+
"docstring" => {
|
22
|
+
"text" => "This is the function documentation for `function3x`",
|
23
|
+
"tags" => [
|
24
|
+
{
|
25
|
+
"tag_name"=>"return",
|
26
|
+
"text"=>"",
|
27
|
+
"types"=>["Any"]
|
28
|
+
}
|
29
|
+
]
|
30
|
+
}
|
31
|
+
},
|
32
|
+
],
|
19
33
|
"docstring" => {
|
20
34
|
"text" => "This is the function documentation for `function3x`",
|
21
35
|
"tags" => ["tag_name" => "return", "text" => "", "types" => ["Any"]]},
|
@@ -84,7 +84,7 @@
|
|
84
84
|
{
|
85
85
|
"name": "database",
|
86
86
|
"file": "(stdin)",
|
87
|
-
"line":
|
87
|
+
"line": 54,
|
88
88
|
"docstring": {
|
89
89
|
"text": "An example database server resource type."
|
90
90
|
},
|
@@ -154,7 +154,7 @@
|
|
154
154
|
"name": "linux",
|
155
155
|
"type_name": "database",
|
156
156
|
"file": "(stdin)",
|
157
|
-
"line":
|
157
|
+
"line": 43,
|
158
158
|
"docstring": {
|
159
159
|
"text": "An example provider on Linux."
|
160
160
|
},
|
@@ -166,9 +166,24 @@
|
|
166
166
|
"implements_some_feature",
|
167
167
|
"some_other_feature"
|
168
168
|
],
|
169
|
-
"defaults":
|
170
|
-
|
171
|
-
|
169
|
+
"defaults": [
|
170
|
+
[
|
171
|
+
[
|
172
|
+
"kernel",
|
173
|
+
"Linux"
|
174
|
+
]
|
175
|
+
],
|
176
|
+
[
|
177
|
+
[
|
178
|
+
"osfamily",
|
179
|
+
"RedHat"
|
180
|
+
],
|
181
|
+
[
|
182
|
+
"operatingsystemmajrelease",
|
183
|
+
"7"
|
184
|
+
]
|
185
|
+
]
|
186
|
+
],
|
172
187
|
"commands": {
|
173
188
|
"foo": "/usr/bin/foo"
|
174
189
|
}
|
@@ -180,7 +195,47 @@
|
|
180
195
|
"file": "(stdin)",
|
181
196
|
"line": 6,
|
182
197
|
"type": "puppet",
|
183
|
-
"
|
198
|
+
"signatures": [
|
199
|
+
{
|
200
|
+
"signature": "func(Integer $param1, Any $param2, String $param3 = hi)",
|
201
|
+
"docstring": {
|
202
|
+
"text": "A simple function.",
|
203
|
+
"tags": [
|
204
|
+
{
|
205
|
+
"tag_name": "param",
|
206
|
+
"text": "First param.",
|
207
|
+
"types": [
|
208
|
+
"Integer"
|
209
|
+
],
|
210
|
+
"name": "param1"
|
211
|
+
},
|
212
|
+
{
|
213
|
+
"tag_name": "param",
|
214
|
+
"text": "Second param.",
|
215
|
+
"types": [
|
216
|
+
"Any"
|
217
|
+
],
|
218
|
+
"name": "param2"
|
219
|
+
},
|
220
|
+
{
|
221
|
+
"tag_name": "param",
|
222
|
+
"text": "Third param.",
|
223
|
+
"types": [
|
224
|
+
"String"
|
225
|
+
],
|
226
|
+
"name": "param3"
|
227
|
+
},
|
228
|
+
{
|
229
|
+
"tag_name": "return",
|
230
|
+
"text": "Returns nothing.",
|
231
|
+
"types": [
|
232
|
+
"Undef"
|
233
|
+
]
|
234
|
+
}
|
235
|
+
]
|
236
|
+
}
|
237
|
+
}
|
238
|
+
],
|
184
239
|
"docstring": {
|
185
240
|
"text": "A simple function.",
|
186
241
|
"tags": [
|
@@ -227,7 +282,39 @@
|
|
227
282
|
"file": "(stdin)",
|
228
283
|
"line": 1,
|
229
284
|
"type": "ruby3x",
|
230
|
-
"
|
285
|
+
"signatures": [
|
286
|
+
{
|
287
|
+
"signature": "func3x(String $first, Any $second)",
|
288
|
+
"docstring": {
|
289
|
+
"text": "An example 3.x function.",
|
290
|
+
"tags": [
|
291
|
+
{
|
292
|
+
"tag_name": "param",
|
293
|
+
"text": "The first parameter.",
|
294
|
+
"types": [
|
295
|
+
"String"
|
296
|
+
],
|
297
|
+
"name": "first"
|
298
|
+
},
|
299
|
+
{
|
300
|
+
"tag_name": "param",
|
301
|
+
"text": "The second parameter.",
|
302
|
+
"types": [
|
303
|
+
"Any"
|
304
|
+
],
|
305
|
+
"name": "second"
|
306
|
+
},
|
307
|
+
{
|
308
|
+
"tag_name": "return",
|
309
|
+
"text": "Returns nothing.",
|
310
|
+
"types": [
|
311
|
+
"Undef"
|
312
|
+
]
|
313
|
+
}
|
314
|
+
]
|
315
|
+
}
|
316
|
+
}
|
317
|
+
],
|
231
318
|
"docstring": {
|
232
319
|
"text": "An example 3.x function.",
|
233
320
|
"tags": [
|
@@ -263,6 +350,78 @@
|
|
263
350
|
"file": "(stdin)",
|
264
351
|
"line": 11,
|
265
352
|
"type": "ruby4x",
|
353
|
+
"signatures": [
|
354
|
+
{
|
355
|
+
"signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)",
|
356
|
+
"docstring": {
|
357
|
+
"text": "The first overload.",
|
358
|
+
"tags": [
|
359
|
+
{
|
360
|
+
"tag_name": "param",
|
361
|
+
"text": "The first parameter.",
|
362
|
+
"types": [
|
363
|
+
"Integer"
|
364
|
+
],
|
365
|
+
"name": "param1"
|
366
|
+
},
|
367
|
+
{
|
368
|
+
"tag_name": "param",
|
369
|
+
"text": "The second parameter.",
|
370
|
+
"types": [
|
371
|
+
"Any"
|
372
|
+
],
|
373
|
+
"name": "param2"
|
374
|
+
},
|
375
|
+
{
|
376
|
+
"tag_name": "param",
|
377
|
+
"text": "The third parameter.",
|
378
|
+
"types": [
|
379
|
+
"Optional[Array[String]]"
|
380
|
+
],
|
381
|
+
"name": "param3"
|
382
|
+
},
|
383
|
+
{
|
384
|
+
"tag_name": "return",
|
385
|
+
"text": "Returns nothing.",
|
386
|
+
"types": [
|
387
|
+
"Undef"
|
388
|
+
]
|
389
|
+
}
|
390
|
+
]
|
391
|
+
}
|
392
|
+
},
|
393
|
+
{
|
394
|
+
"signature": "func4x(Boolean $param, Callable &$block)",
|
395
|
+
"docstring": {
|
396
|
+
"text": "",
|
397
|
+
"tags": [
|
398
|
+
{
|
399
|
+
"tag_name": "param",
|
400
|
+
"text": "The first parameter.",
|
401
|
+
"types": [
|
402
|
+
"Boolean"
|
403
|
+
],
|
404
|
+
"name": "param"
|
405
|
+
},
|
406
|
+
{
|
407
|
+
"tag_name": "param",
|
408
|
+
"text": "The block parameter.",
|
409
|
+
"types": [
|
410
|
+
"Callable"
|
411
|
+
],
|
412
|
+
"name": "&block"
|
413
|
+
},
|
414
|
+
{
|
415
|
+
"tag_name": "return",
|
416
|
+
"text": "Returns a string.",
|
417
|
+
"types": [
|
418
|
+
"String"
|
419
|
+
]
|
420
|
+
}
|
421
|
+
]
|
422
|
+
}
|
423
|
+
}
|
424
|
+
],
|
266
425
|
"docstring": {
|
267
426
|
"text": "An example 4.x function.",
|
268
427
|
"tags": [
|
@@ -311,7 +470,7 @@
|
|
311
470
|
"tag_name": "overload",
|
312
471
|
"signature": "func4x(Boolean $param, Callable &$block)",
|
313
472
|
"docstring": {
|
314
|
-
"text": "
|
473
|
+
"text": "",
|
315
474
|
"tags": [
|
316
475
|
{
|
317
476
|
"tag_name": "param",
|
@@ -342,7 +501,59 @@
|
|
342
501
|
}
|
343
502
|
]
|
344
503
|
},
|
345
|
-
"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
|
504
|
+
"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"
|
505
|
+
},
|
506
|
+
{
|
507
|
+
"name": "func4x_1",
|
508
|
+
"file": "(stdin)",
|
509
|
+
"line": 35,
|
510
|
+
"type": "ruby4x",
|
511
|
+
"signatures": [
|
512
|
+
{
|
513
|
+
"signature": "func4x_1(Integer $param1)",
|
514
|
+
"docstring": {
|
515
|
+
"text": "An example 4.x function with only one signature.",
|
516
|
+
"tags": [
|
517
|
+
{
|
518
|
+
"tag_name": "param",
|
519
|
+
"text": "The first parameter.",
|
520
|
+
"types": [
|
521
|
+
"Integer"
|
522
|
+
],
|
523
|
+
"name": "param1"
|
524
|
+
},
|
525
|
+
{
|
526
|
+
"tag_name": "return",
|
527
|
+
"text": "Returns nothing.",
|
528
|
+
"types": [
|
529
|
+
"Undef"
|
530
|
+
]
|
531
|
+
}
|
532
|
+
]
|
533
|
+
}
|
534
|
+
}
|
535
|
+
],
|
536
|
+
"docstring": {
|
537
|
+
"text": "An example 4.x function with only one signature.",
|
538
|
+
"tags": [
|
539
|
+
{
|
540
|
+
"tag_name": "param",
|
541
|
+
"text": "The first parameter.",
|
542
|
+
"types": [
|
543
|
+
"Integer"
|
544
|
+
],
|
545
|
+
"name": "param1"
|
546
|
+
},
|
547
|
+
{
|
548
|
+
"tag_name": "return",
|
549
|
+
"text": "Returns nothing.",
|
550
|
+
"types": [
|
551
|
+
"Undef"
|
552
|
+
]
|
553
|
+
}
|
554
|
+
]
|
555
|
+
},
|
556
|
+
"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"
|
346
557
|
}
|
347
558
|
]
|
348
559
|
}
|