puppet-strings 1.0.0 → 1.1.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.
Files changed (37) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +12 -0
  3. data/Gemfile +4 -4
  4. data/MAINTAINERS +17 -0
  5. data/README.md +27 -10
  6. data/Rakefile +13 -3
  7. data/lib/puppet-strings/yard.rb +3 -0
  8. data/lib/puppet-strings/yard/handlers/helpers.rb +8 -0
  9. data/lib/puppet-strings/yard/handlers/puppet/base.rb +2 -2
  10. data/lib/puppet-strings/yard/handlers/puppet/class_handler.rb +4 -0
  11. data/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb +4 -0
  12. data/lib/puppet-strings/yard/handlers/puppet/function_handler.rb +4 -0
  13. data/lib/puppet-strings/yard/handlers/ruby/function_handler.rb +4 -0
  14. data/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb +4 -0
  15. data/lib/puppet-strings/yard/handlers/ruby/type_handler.rb +4 -0
  16. data/lib/puppet-strings/yard/tags.rb +1 -0
  17. data/lib/puppet-strings/yard/tags/summary_tag.rb +9 -0
  18. data/lib/puppet-strings/yard/templates/default/puppet_class/html/setup.rb +1 -1
  19. data/lib/puppet-strings/yard/templates/default/puppet_class/html/summary.erb +4 -0
  20. data/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/setup.rb +1 -1
  21. data/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/summary.erb +4 -0
  22. data/lib/puppet-strings/yard/templates/default/puppet_function/html/setup.rb +1 -1
  23. data/lib/puppet-strings/yard/templates/default/puppet_function/html/summary.erb +4 -0
  24. data/lib/puppet-strings/yard/templates/default/puppet_provider/html/setup.rb +1 -1
  25. data/lib/puppet-strings/yard/templates/default/puppet_provider/html/summary.erb +4 -0
  26. data/lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb +1 -1
  27. data/lib/puppet-strings/yard/templates/default/puppet_type/html/summary.erb +4 -0
  28. data/spec/acceptance/lib/util.rb +148 -0
  29. data/spec/spec_helper_acceptance.rb +6 -5
  30. data/spec/unit/puppet-strings/json_spec.rb +1 -1
  31. data/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb +64 -2
  32. data/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb +71 -2
  33. data/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb +61 -2
  34. data/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb +39 -0
  35. data/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb +31 -0
  36. data/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb +31 -0
  37. metadata +11 -3
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 2beba5e6c9153efb0208b8dd2fe19eb0ae1ea589
4
- data.tar.gz: f64ddfa0a74a5aeef8e525cbb59512888dd6bc2f
3
+ metadata.gz: 1c66cddb3ce959fa86315c18de4cfd36e9c4b332
4
+ data.tar.gz: f71b3c4062b8ca1155c619d3634ca6da4ff0e2c1
5
5
  SHA512:
6
- metadata.gz: 144215672c483f72a13b23897613fdf7440e6c6ce4d4310b407d7192a889037e58a1bc38a4a9d40b3fbf121c91bde7ccca2e126a374e91828a768c8a69b04405
7
- data.tar.gz: 1e3525e0d4689fee040d12c9dac44f6184803d49327aa6707d18d64d641543deea47e526adf38c5a3af2dab4da6c1e46f86612c52fe747bbadabd4a71102b7e6
6
+ metadata.gz: 8aec3266ab3f8dccc3b6d8417c9862d07fd9f7c4d53e5945ebd0b502fb01ca5e3d31264ec71971799d5e61580bbb6d097b97a28ecba98acf331a7b095c658c0d
7
+ data.tar.gz: e1f0b911bdef1670b9db4beab036683cfd241193330008e44d443a83a235e17661ebfbbcc6995daa80381b29c2f166036af7d869659b6861cfbfd74355821621
@@ -1,3 +1,15 @@
1
+ ##2017-03-20 - Release 1.1.0
2
+
3
+ ###Summary
4
+
5
+ This release adds a new `summary` tag which can be used to add a short description to classes, functions, types, and providers. In addition, `@param` tags can now include type information in Puppet 4 code without warnings being issued.
6
+
7
+ All related tickets can be found under the [PDOC](https://tickets.puppetlabs.com/browse/PDOC) JIRA project with the fix version of [1.1.0](https://tickets.puppetlabs.com/issues/?filter=25603).
8
+
9
+ ###Features
10
+ - The `summary` tag can be added to any code that puppet-strings supports. The recommended length limit for a summary is 140 characters. Warnings will be issued for strings longer than this limit.
11
+ - Puppet 4 parameter types can now be explicitly documented. Previously, this was not allowed because Puppet 4 parameter types can be automatically determined without extra documentation. However, users may desire to do so anyway for consistency. Strings will emit a warning if the documented type does not match the actual type. In such an event, the incorrect documented type will be ignored in favor of the real one.
12
+
1
13
  ##2016-11-28 - Release 1.0.0
2
14
 
3
15
  ###Summary
data/Gemfile CHANGED
@@ -4,7 +4,7 @@ gemspec
4
4
 
5
5
  gem 'rgen'
6
6
  gem 'redcarpet'
7
- gem 'yard', '~> 0.9.5'
7
+ gem 'yard', '0.9.5'
8
8
 
9
9
  if ENV['PUPPET_GEM_VERSION']
10
10
  gem 'puppet', ENV['PUPPET_GEM_VERSION'], :require => false
@@ -34,6 +34,6 @@ group :development do
34
34
  end
35
35
  end
36
36
 
37
- gem 'json', '<= 1.8' if RUBY_VERSION < '2.0.0'
38
- gem 'json_pure', '<= 2.0.1' if RUBY_VERSION < '2.0.0'
39
- gem 'rubocop' if RUBY_VERSION >= '2.0.0'
37
+ gem 'json', '<= 1.8' if RUBY_VERSION < '2.0.0'
38
+ gem 'json_pure', '<= 2.0.1' if RUBY_VERSION < '2.0.0'
39
+ gem 'rubocop', '<= 0.47.0' if RUBY_VERSION >= '2.0.0'
@@ -0,0 +1,17 @@
1
+ {
2
+ "version": 1,
3
+ "file_format": "This MAINTAINERS file format is described at http://pup.pt/maintainers",
4
+ "issues": "https://tickets.puppetlabs.com/browse/PDOC",
5
+ "people": [
6
+ {
7
+ "github": "whopper",
8
+ "email": "whopper@puppet.com",
9
+ "name": "Will Hopper"
10
+ },
11
+ {
12
+ "github": "scotje",
13
+ "email": "jesse@puppet.com",
14
+ "name": "Jesse Scott"
15
+ }
16
+ ]
17
+ }
data/README.md CHANGED
@@ -49,13 +49,20 @@ For Puppet 3.x:
49
49
  $ puppet resource package yard provider=gem
50
50
  ```
51
51
 
52
- For Puppet Enterprise 3.8:
52
+ For Puppet Enterprise 3.8 (Linux):
53
53
 
54
54
  ```
55
55
  GEM_HOME=/opt/puppet/lib/ruby/gems/1.9.1 puppet resource package yard provider=gem
56
56
  ```
57
57
 
58
- ### 2. Puppet Enterprise 3.8 only: Install the redcarpet gem
58
+ For Puppet Enterprise 3.8 (Windows):
59
+
60
+ ```
61
+ $env:GEM_HOME = "C:\Program Files\Puppet Labs\Puppet Enterprise\sys\ruby\lib\ruby\gems\2.0.0"
62
+ puppet resource package yard provider=gem
63
+ ```
64
+
65
+ ### 2. Puppet Enterprise 3.8 in Linux only: Install the redcarpet gem
59
66
 
60
67
  ```
61
68
  GEM_HOME=/opt/puppet/lib/ruby/gems/1.9.1 puppet resource package redcarpet provider=gem
@@ -77,12 +84,19 @@ For Puppet 3.x:
77
84
  $ puppet resource package puppet-strings provider=gem
78
85
  ```
79
86
 
80
- For Puppet Enterprise 3.8:
87
+ For Puppet Enterprise 3.8 (Linux):
81
88
 
82
89
  ```
83
90
  GEM_HOME=/opt/puppet/lib/ruby/gems/1.9.1 puppet resource package puppet-strings provider=gem
84
91
  ```
85
92
 
93
+ For Puppet Enterprise 3.8 (Windows)
94
+
95
+ ```
96
+ $env:GEM_HOME = "C:\Program Files\Puppet Labs\Puppet Enterprise\sys\ruby\lib\ruby\gems\2.0.0"
97
+ puppet resource package puppet-strings provider=gem
98
+ ```
99
+
86
100
  ### 4. Optional: Set YARD options for Strings
87
101
 
88
102
  Puppet Strings supports YARD options (on the command line, run `yard help doc` for a list of possible options. To set YARD options, specify a `yardopts` file in the same directory in which you run `puppet strings`.
@@ -176,6 +190,8 @@ To document Puppet classes and defined types, use a series of comments to create
176
190
  #
177
191
  # This is an example of how to document a Puppet class
178
192
  #
193
+ # @summary A short summary of the purpose of the class.
194
+ #
179
195
  # @example Declaring the class
180
196
  # include example
181
197
  #
@@ -192,19 +208,20 @@ class example_class(
192
208
  The Strings elements appearing in the above comment block are:
193
209
 
194
210
  * Three comment lines, not prefixed with tags, give the class description.
211
+ * The `@summary` YARD tag, which can be used for a short description of the class (fewer than 140 characters recommended).
195
212
  * The `@example` YARD tag, immediately followed by an optional title.
196
213
  * The `include` statement, which adds the usage example code.
197
214
  * Two `@param` tags, with the name of the parameter first, followed by a string describing the parameter's purpose.
198
215
 
199
- Puppet 4 is a typed language, so Puppet Strings automatically documents the parameter types from code. With Puppet 3, however, include the parameter type with the `@param` tag:
216
+ Puppet 4 is a typed language, so Puppet Strings automatically documents the parameter types from code. You may optionally include a parameter type in the `@param` tag. Strings will emit a warning and ignore the documented type should it differ from the actual type.
217
+
218
+ With Puppet 3 code, you must always include the parameter type with the `@param` tag:
200
219
 
201
220
  ```
202
- # @param [String] first The first parameter for this class.
203
- # @param [Integer] second The second parameter for this class.
221
+ # @param first [String] The first parameter for this class.
222
+ # @param second [Integer] The second parameter for this class.
204
223
  ```
205
224
 
206
- Note that if you document a parameter's type, and that parameter already has a Puppet type specifier, Strings emits a warning.
207
-
208
225
  Defined types are documented in exactly the same way as classes:
209
226
 
210
227
  ```
@@ -332,8 +349,8 @@ To document a function in the Puppet 3 API, use the `doc` option to `newfunction
332
349
  ```ruby
333
350
  Puppet::Parser::Functions.newfunction(:example, doc: <<-DOC
334
351
  Documentation for an example 3.x function.
335
- @param [String] param1 The first parameter.
336
- @param [Integer] param2 The second parameter.
352
+ @param param1 [String] The first parameter.
353
+ @param param2 [Integer] The second parameter.
337
354
  @return [Undef]
338
355
  @example Calling the function.
339
356
  example('hi', 10)
data/Rakefile CHANGED
@@ -21,12 +21,17 @@ end
21
21
  task :acceptance do
22
22
  require 'beaker-hostgenerator'
23
23
 
24
+ install_type = 'aio'
24
25
  target = ENV['platform']
25
26
  if ! target
26
27
  STDERR.puts 'TEST_TARGET environment variable is not set'
27
28
  STDERR.puts 'setting to default value of "centos7-64ma".'
28
- target = 'centos7-64ma'
29
- ENV['platform'] = target
29
+ target = "centos7-64ma{type=#{install_type}}"
30
+ end
31
+
32
+ unless target =~ /type=/
33
+ puts "INFO: adding 'type=#{install_type}' to host config"
34
+ target += "{type=#{install_type}}"
30
35
  end
31
36
 
32
37
  cli = BeakerHostGenerator::CLI.new([target])
@@ -36,10 +41,15 @@ task :acceptance do
36
41
  File.open(nodeset, 'w') do |fh|
37
42
  fh.print(cli.execute)
38
43
  end
44
+ puts "nodeset file:"
39
45
  puts nodeset
40
46
  sh 'gem build puppet-strings.gemspec'
41
47
  sh 'puppet module build spec/fixtures/acceptance/modules/test'
42
- sh "BEAKER_set=#{ENV['platform']} rspec spec/acceptance/*.rb"
48
+ if ENV['BEAKER_keyfile']
49
+ sh "BEAKER_set=#{target} rspec spec/acceptance/*.rb"
50
+ else
51
+ sh "BEAKER_keyfile=$HOME/.ssh/id_rsa-acceptance BEAKER_set=#{target} rspec spec/acceptance/*.rb"
52
+ end
43
53
  end
44
54
 
45
55
  task(:rubocop) do
@@ -24,6 +24,9 @@ module PuppetStrings::Yard
24
24
  PuppetStrings::Yard::Tags::ParameterDirective.register!
25
25
  PuppetStrings::Yard::Tags::PropertyDirective.register!
26
26
 
27
+ # Register the summary tag
28
+ PuppetStrings::Yard::Tags::SummaryTag.register!
29
+
27
30
  # Ignore documentation on Puppet DSL calls
28
31
  # This prevents the YARD DSL parser from emitting warnings for Puppet's Ruby DSL
29
32
  YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS['create_function'] = true
@@ -0,0 +1,8 @@
1
+ module PuppetStrings::Yard::Handlers::Helpers
2
+ # Logs a warning if a summary tag has more than 140 characters
3
+ def self.validate_summary_tag(object)
4
+ if object.has_tag?(:summary) && object.tag(:summary).text.length > 140
5
+ log.warn "The length of the summary for #{object.type} '#{object.name}' exceeds the recommended limit of 140 characters."
6
+ end
7
+ end
8
+ end
@@ -31,8 +31,8 @@ class PuppetStrings::Yard::Handlers::Puppet::Base < YARD::Handlers::Base
31
31
  next
32
32
  end
33
33
 
34
- # Warn if the parameter is typed and the tag also has a type
35
- log.warn "The @param tag for parameter '#{parameter.name}' should not contain a type specification near #{statement.file}:#{statement.line}: ignoring in favor of parameter type information." if parameter.type && tag.types && !tag.types.empty?
34
+ # Warn if the parameter type and tag types don't match
35
+ log.warn "The type of the @param tag for parameter '#{parameter.name}' does not match the parameter type specification near #{statement.file}:#{statement.line}: ignoring in favor of parameter type information." if parameter.type && tag.types && !tag.types.empty? && parameter.type != tag.types[0]
36
36
 
37
37
  if parameter.type
38
38
  tag.types = [parameter.type]
@@ -1,3 +1,4 @@
1
+ require 'puppet-strings/yard/handlers/helpers'
1
2
  require 'puppet-strings/yard/handlers/puppet/base'
2
3
  require 'puppet-strings/yard/parsers'
3
4
  require 'puppet-strings/yard/code_objects'
@@ -19,5 +20,8 @@ class PuppetStrings::Yard::Handlers::Puppet::ClassHandler < PuppetStrings::Yard:
19
20
 
20
21
  # Mark the class as public if it doesn't already have an api tag
21
22
  object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
23
+
24
+ # Warn if a summary longer than 140 characters was provided
25
+ PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
22
26
  end
23
27
  end
@@ -1,3 +1,4 @@
1
+ require 'puppet-strings/yard/handlers/helpers'
1
2
  require 'puppet-strings/yard/handlers/puppet/base'
2
3
  require 'puppet-strings/yard/parsers'
3
4
  require 'puppet-strings/yard/code_objects'
@@ -19,5 +20,8 @@ class PuppetStrings::Yard::Handlers::Puppet::DefinedTypeHandler < PuppetStrings:
19
20
 
20
21
  # Mark the defined type as public if it doesn't already have an api tag
21
22
  object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
23
+
24
+ # Warn if a summary longer than 140 characters was provided
25
+ PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
22
26
  end
23
27
  end
@@ -1,3 +1,4 @@
1
+ require 'puppet-strings/yard/handlers/helpers'
1
2
  require 'puppet-strings/yard/handlers/puppet/base'
2
3
  require 'puppet-strings/yard/parsers'
3
4
  require 'puppet-strings/yard/code_objects'
@@ -27,6 +28,9 @@ class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Ya
27
28
 
28
29
  # Mark the class as public if it doesn't already have an api tag
29
30
  object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
31
+
32
+ # Warn if a summary longer than 140 characters was provided
33
+ PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
30
34
  end
31
35
 
32
36
  private
@@ -1,3 +1,4 @@
1
+ require 'puppet-strings/yard/handlers/helpers'
1
2
  require 'puppet-strings/yard/handlers/ruby/base'
2
3
  require 'puppet-strings/yard/code_objects'
3
4
  require 'puppet-strings/yard/util'
@@ -61,6 +62,9 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
61
62
 
62
63
  # Mark the function as public if it doesn't already have an api tag
63
64
  object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
65
+
66
+ # Warn if a summary longer than 140 characters was provided
67
+ PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
64
68
  end
65
69
 
66
70
  private
@@ -1,3 +1,4 @@
1
+ require 'puppet-strings/yard/handlers/helpers'
1
2
  require 'puppet-strings/yard/handlers/ruby/base'
2
3
  require 'puppet-strings/yard/code_objects'
3
4
  require 'puppet-strings/yard/util'
@@ -34,6 +35,9 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard
34
35
 
35
36
  # Mark the provider as public if it doesn't already have an api tag
36
37
  object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
38
+
39
+ # Warn if a summary longer than 140 characters was provided
40
+ PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
37
41
  end
38
42
 
39
43
  private
@@ -1,3 +1,4 @@
1
+ require 'puppet-strings/yard/handlers/helpers'
1
2
  require 'puppet-strings/yard/handlers/ruby/base'
2
3
  require 'puppet-strings/yard/code_objects'
3
4
  require 'puppet-strings/yard/util'
@@ -30,6 +31,9 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha
30
31
 
31
32
  # Mark the type as public if it doesn't already have an api tag
32
33
  object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api
34
+
35
+ # Warn if a summary longer than 140 characters was provided
36
+ PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary
33
37
  end
34
38
 
35
39
  private
@@ -3,4 +3,5 @@ module PuppetStrings::Yard::Tags
3
3
  require 'puppet-strings/yard/tags/parameter_directive'
4
4
  require 'puppet-strings/yard/tags/property_directive'
5
5
  require 'puppet-strings/yard/tags/overload_tag'
6
+ require 'puppet-strings/yard/tags/summary_tag'
6
7
  end
@@ -0,0 +1,9 @@
1
+ # Implements a summary tag for general purpose short descriptions
2
+
3
+ class PuppetStrings::Yard::Tags::SummaryTag < YARD::Tags::Tag
4
+ # Registers the tag with YARD.
5
+ # @return [void]
6
+ def self.register!
7
+ YARD::Tags::Library.define_tag("puppet.summary", :summary)
8
+ end
9
+ end
@@ -1,7 +1,7 @@
1
1
  # Initializes the template.
2
2
  # @return [void]
3
3
  def init
4
- sections :header, :box_info, :overview, T('tags'), :source
4
+ sections :header, :box_info, :summary, :overview, T('tags'), :source
5
5
  end
6
6
 
7
7
  # Renders the box_info section.
@@ -0,0 +1,4 @@
1
+ <% if object.docstring.has_tag?(:summary) %>
2
+ <h2>Summary</h2>
3
+ <%= object.docstring.tag(:summary).text %>
4
+ <% end %>
@@ -1,5 +1,5 @@
1
1
  # Initializes the template.
2
2
  # @return [void]
3
3
  def init
4
- sections :header, :box_info, :overview, T('tags'), :source
4
+ sections :header, :box_info, :summary, :overview, T('tags'), :source
5
5
  end
@@ -0,0 +1,4 @@
1
+ <% if object.docstring.has_tag?(:summary) %>
2
+ <h2>Summary</h2>
3
+ <%= object.docstring.tag(:summary).text %>
4
+ <% end %>
@@ -1,5 +1,5 @@
1
1
  # Initializes the template.
2
2
  # @return [void]
3
3
  def init
4
- sections :header, :box_info, :overview, [T('tags'), :source]
4
+ sections :header, :box_info, :summary, :overview, [T('tags'), :source]
5
5
  end
@@ -0,0 +1,4 @@
1
+ <% if object.docstring.has_tag?(:summary) %>
2
+ <h2>Summary</h2>
3
+ <%= object.docstring.tag(:summary).text %>
4
+ <% end %>
@@ -1,7 +1,7 @@
1
1
  # Initializes the template.
2
2
  # @return [void]
3
3
  def init
4
- sections :header, :box_info, :overview, T('tags'), :features, :confines, :defaults, :commands
4
+ sections :header, :box_info, :summary, :overview, T('tags'), :features, :confines, :defaults, :commands
5
5
  end
6
6
 
7
7
  # Renders the confines section.
@@ -0,0 +1,4 @@
1
+ <% if object.docstring.has_tag?(:summary) %>
2
+ <h2>Summary</h2>
3
+ <%= object.docstring.tag(:summary).text %>
4
+ <% end %>
@@ -1,7 +1,7 @@
1
1
  # Initializes the template.
2
2
  # @return [void]
3
3
  def init
4
- sections :header, :box_info, :overview, T('tags'), :properties, :parameters, :features
4
+ sections :header, :box_info, :summary, :overview, T('tags'), :properties, :parameters, :features
5
5
  end
6
6
 
7
7
  # Renders the box_info section.
@@ -0,0 +1,4 @@
1
+ <% if object.docstring.has_tag?(:summary) %>
2
+ <h2>Summary</h2>
3
+ <%= object.docstring.tag(:summary).text %>
4
+ <% end %>
@@ -1,6 +1,104 @@
1
1
  module PuppetStrings
2
2
  module Acceptance
3
3
  module Util
4
+ GEOTRUST_GLOBAL_CA = <<-EOM
5
+ -----BEGIN CERTIFICATE-----
6
+ MIIDVDCCAjygAwIBAgIDAjRWMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT
7
+ MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMRswGQYDVQQDExJHZW9UcnVzdCBHbG9i
8
+ YWwgQ0EwHhcNMDIwNTIxMDQwMDAwWhcNMjIwNTIxMDQwMDAwWjBCMQswCQYDVQQG
9
+ EwJVUzEWMBQGA1UEChMNR2VvVHJ1c3QgSW5jLjEbMBkGA1UEAxMSR2VvVHJ1c3Qg
10
+ R2xvYmFsIENBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2swYYzD9
11
+ 9BcjGlZ+W988bDjkcbd4kdS8odhM+KhDtgPpTSEHCIjaWC9mOSm9BXiLnTjoBbdq
12
+ fnGk5sRgprDvgOSJKA+eJdbtg/OtppHHmMlCGDUUna2YRpIuT8rxh0PBFpVXLVDv
13
+ iS2Aelet8u5fa9IAjbkU+BQVNdnARqN7csiRv8lVK83Qlz6cJmTM386DGXHKTubU
14
+ 1XupGc1V3sjs0l44U+VcT4wt/lAjNvxm5suOpDkZALeVAjmRCw7+OC7RHQWa9k0+
15
+ bw8HHa8sHo9gOeL6NlMTOdReJivbPagUvTLrGAMoUgRx5aszPeE4uwc2hGKceeoW
16
+ MPRfwCvocWvk+QIDAQABo1MwUTAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBTA
17
+ ephojYn7qwVkDBF9qn1luMrMTjAfBgNVHSMEGDAWgBTAephojYn7qwVkDBF9qn1l
18
+ uMrMTjANBgkqhkiG9w0BAQUFAAOCAQEANeMpauUvXVSOKVCUn5kaFOSPeCpilKIn
19
+ Z57QzxpeR+nBsqTP3UEaBU6bS+5Kb1VSsyShNwrrZHYqLizz/Tt1kL/6cdjHPTfS
20
+ tQWVYrmm3ok9Nns4d0iXrKYgjy6myQzCsplFAMfOEVEiIuCl6rYVSAlk6l5PdPcF
21
+ PseKUgzbFbS9bZvlxrFUaKnjaZC2mqUPuLk/IH2uSrW4nOQdtqvmlKXBx4Ot2/Un
22
+ hw4EbNX/3aBd7YdStysVAq45pmp06drE57xNNB6pXE0zX5IJL4hmXXeXxx12E6nV
23
+ 5fEWCRE11azbJHFwLJhWC9kXtNHjUStedejV0NxPNO3CBWaAocvmMw==
24
+ -----END CERTIFICATE-----
25
+ EOM
26
+
27
+ USERTRUST_NETWORK_CA = <<-EOM
28
+ -----BEGIN CERTIFICATE-----
29
+ MIIEdDCCA1ygAwIBAgIQRL4Mi1AAJLQR0zYq/mUK/TANBgkqhkiG9w0BAQUFADCB
30
+ lzELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAlVUMRcwFQYDVQQHEw5TYWx0IExha2Ug
31
+ Q2l0eTEeMBwGA1UEChMVVGhlIFVTRVJUUlVTVCBOZXR3b3JrMSEwHwYDVQQLExho
32
+ dHRwOi8vd3d3LnVzZXJ0cnVzdC5jb20xHzAdBgNVBAMTFlVUTi1VU0VSRmlyc3Qt
33
+ SGFyZHdhcmUwHhcNOTkwNzA5MTgxMDQyWhcNMTkwNzA5MTgxOTIyWjCBlzELMAkG
34
+ A1UEBhMCVVMxCzAJBgNVBAgTAlVUMRcwFQYDVQQHEw5TYWx0IExha2UgQ2l0eTEe
35
+ MBwGA1UEChMVVGhlIFVTRVJUUlVTVCBOZXR3b3JrMSEwHwYDVQQLExhodHRwOi8v
36
+ d3d3LnVzZXJ0cnVzdC5jb20xHzAdBgNVBAMTFlVUTi1VU0VSRmlyc3QtSGFyZHdh
37
+ cmUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCx98M4P7Sof885glFn
38
+ 0G2f0v9Y8+efK+wNiVSZuTiZFvfgIXlIwrthdBKWHTxqctU8EGc6Oe0rE81m65UJ
39
+ M6Rsl7HoxuzBdXmcRl6Nq9Bq/bkqVRcQVLMZ8Jr28bFdtqdt++BxF2uiiPsA3/4a
40
+ MXcMmgF6sTLjKwEHOG7DpV4jvEWbe1DByTCP2+UretNb+zNAHqDVmBe8i4fDidNd
41
+ oI6yqqr2jmmIBsX6iSHzCJ1pLgkzmykNRg+MzEk0sGlRvfkGzWitZky8PqxhvQqI
42
+ DsjfPe58BEydCl5rkdbux+0ojatNh4lz0G6k0B4WixThdkQDf2Os5M1JnMWS9Ksy
43
+ oUhbAgMBAAGjgbkwgbYwCwYDVR0PBAQDAgHGMA8GA1UdEwEB/wQFMAMBAf8wHQYD
44
+ VR0OBBYEFKFyXyYbKJhDlV0HN9WFlp1L0sNFMEQGA1UdHwQ9MDswOaA3oDWGM2h0
45
+ dHA6Ly9jcmwudXNlcnRydXN0LmNvbS9VVE4tVVNFUkZpcnN0LUhhcmR3YXJlLmNy
46
+ bDAxBgNVHSUEKjAoBggrBgEFBQcDAQYIKwYBBQUHAwUGCCsGAQUFBwMGBggrBgEF
47
+ BQcDBzANBgkqhkiG9w0BAQUFAAOCAQEARxkP3nTGmZev/K0oXnWO6y1n7k57K9cM
48
+ //bey1WiCuFMVGWTYGufEpytXoMs61quwOQt9ABjHbjAbPLPSbtNk28Gpgoiskli
49
+ CE7/yMgUsogWXecB5BKV5UU0s4tpvc+0hY91UZ59Ojg6FEgSxvunOxqNDYJAB+gE
50
+ CJChicsZUN/KHAG8HQQZexB2lzvukJDKxA4fFm517zP4029bHpbj4HR3dHuKom4t
51
+ 3XbWOTCC8KucUvIqx69JXn7HaOWCgchqJ/kniCrVWFCVH/A7HFe7fRQ5YiuayZSS
52
+ KqMiDP+JJn1fIytH1xUdqWqeUQ0qUZ6B+dQ7XnASfxAynB67nfhmqA==
53
+ -----END CERTIFICATE-----
54
+ EOM
55
+
56
+ EQUIFAX_CA = <<-EOM
57
+ -----BEGIN CERTIFICATE-----
58
+ MIIDIDCCAomgAwIBAgIENd70zzANBgkqhkiG9w0BAQUFADBOMQswCQYDVQQGEwJV
59
+ UzEQMA4GA1UEChMHRXF1aWZheDEtMCsGA1UECxMkRXF1aWZheCBTZWN1cmUgQ2Vy
60
+ dGlmaWNhdGUgQXV0aG9yaXR5MB4XDTk4MDgyMjE2NDE1MVoXDTE4MDgyMjE2NDE1
61
+ MVowTjELMAkGA1UEBhMCVVMxEDAOBgNVBAoTB0VxdWlmYXgxLTArBgNVBAsTJEVx
62
+ dWlmYXggU2VjdXJlIENlcnRpZmljYXRlIEF1dGhvcml0eTCBnzANBgkqhkiG9w0B
63
+ AQEFAAOBjQAwgYkCgYEAwV2xWGcIYu6gmi0fCG2RFGiYCh7+2gRvE4RiIcPRfM6f
64
+ BeC4AfBONOziipUEZKzxa1NfBbPLZ4C/QgKO/t0BCezhABRP/PvwDN1Dulsr4R+A
65
+ cJkVV5MW8Q+XarfCaCMczE1ZMKxRHjuvK9buY0V7xdlfUNLjUA86iOe/FP3gx7kC
66
+ AwEAAaOCAQkwggEFMHAGA1UdHwRpMGcwZaBjoGGkXzBdMQswCQYDVQQGEwJVUzEQ
67
+ MA4GA1UEChMHRXF1aWZheDEtMCsGA1UECxMkRXF1aWZheCBTZWN1cmUgQ2VydGlm
68
+ aWNhdGUgQXV0aG9yaXR5MQ0wCwYDVQQDEwRDUkwxMBoGA1UdEAQTMBGBDzIwMTgw
69
+ ODIyMTY0MTUxWjALBgNVHQ8EBAMCAQYwHwYDVR0jBBgwFoAUSOZo+SvSspXXR9gj
70
+ IBBPM5iQn9QwHQYDVR0OBBYEFEjmaPkr0rKV10fYIyAQTzOYkJ/UMAwGA1UdEwQF
71
+ MAMBAf8wGgYJKoZIhvZ9B0EABA0wCxsFVjMuMGMDAgbAMA0GCSqGSIb3DQEBBQUA
72
+ A4GBAFjOKer89961zgK5F7WF0bnj4JXMJTENAKaSbn+2kmOeUJXRmm/kEd5jhW6Y
73
+ 7qj/WsjTVbJmcVfewCHrPSqnI0kBBIZCe/zuf6IWUrVnZ9NA2zsmWLIodz2uFHdh
74
+ 1voqZiegDfqnc1zqcPGUIWVEX/r87yloqaKHee9570+sB3c4
75
+ -----END CERTIFICATE-----
76
+ EOM
77
+
78
+ GLOBALSIGN_CA = <<-EOM
79
+ -----BEGIN CERTIFICATE-----
80
+ MIIDdTCCAl2gAwIBAgILBAAAAAABFUtaw5QwDQYJKoZIhvcNAQEFBQAwVzELMAkG
81
+ A1UEBhMCQkUxGTAXBgNVBAoTEEdsb2JhbFNpZ24gbnYtc2ExEDAOBgNVBAsTB1Jv
82
+ b3QgQ0ExGzAZBgNVBAMTEkdsb2JhbFNpZ24gUm9vdCBDQTAeFw05ODA5MDExMjAw
83
+ MDBaFw0yODAxMjgxMjAwMDBaMFcxCzAJBgNVBAYTAkJFMRkwFwYDVQQKExBHbG9i
84
+ YWxTaWduIG52LXNhMRAwDgYDVQQLEwdSb290IENBMRswGQYDVQQDExJHbG9iYWxT
85
+ aWduIFJvb3QgQ0EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDaDuaZ
86
+ jc6j40+Kfvvxi4Mla+pIH/EqsLmVEQS98GPR4mdmzxzdzxtIK+6NiY6arymAZavp
87
+ xy0Sy6scTHAHoT0KMM0VjU/43dSMUBUc71DuxC73/OlS8pF94G3VNTCOXkNz8kHp
88
+ 1Wrjsok6Vjk4bwY8iGlbKk3Fp1S4bInMm/k8yuX9ifUSPJJ4ltbcdG6TRGHRjcdG
89
+ snUOhugZitVtbNV4FpWi6cgKOOvyJBNPc1STE4U6G7weNLWLBYy5d4ux2x8gkasJ
90
+ U26Qzns3dLlwR5EiUWMWea6xrkEmCMgZK9FGqkjWZCrXgzT/LCrBbBlDSgeF59N8
91
+ 9iFo7+ryUp9/k5DPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8E
92
+ BTADAQH/MB0GA1UdDgQWBBRge2YaRQ2XyolQL30EzTSo//z9SzANBgkqhkiG9w0B
93
+ AQUFAAOCAQEA1nPnfE920I2/7LqivjTFKDK1fPxsnCwrvQmeU79rXqoRSLblCKOz
94
+ yj1hTdNGCbM+w6DjY1Ub8rrvrTnhQ7k4o+YviiY776BQVvnGCv04zcQLcFGUl5gE
95
+ 38NflNUVyRRBnMRddWQVDf9VMOyGj/8N7yy5Y0b2qvzfvGn9LhJIZJrglfCm7ymP
96
+ AbEVtQwdpf5pLGkkeB6zpxxxYu7KyJesF12KwvhHhm4qxFYxldBniYUr+WymXUad
97
+ DKqC5JlR3XC321Y9YeRq4VzW9v493kHMB65jUr9TU/Qr6cf9tveCX4XSQRjbgbME
98
+ HMUfpIBvFSDJ3gyICh3WZlXi/EjJKSZp4A==
99
+ -----END CERTIFICATE-----
100
+ EOM
101
+
4
102
  def read_file_on(host, filename)
5
103
  on(host, "cat #{filename}").stdout
6
104
  end
@@ -10,6 +108,56 @@ module PuppetStrings
10
108
  test_module_info = modules['modules_by_path'].values.flatten.find { |mod_info| mod_info =~ module_regex }
11
109
  test_module_info.match(/\(([^)]*)\)/)[1]
12
110
  end
111
+
112
+ def install_ca_certs(host)
113
+ return unless host.platform =~ /windows/
114
+
115
+ step "Installing Geotrust CA cert"
116
+ create_remote_file(host, "geotrustglobal.pem", GEOTRUST_GLOBAL_CA)
117
+ on host, "chmod 644 geotrustglobal.pem"
118
+ on host, "cmd /c certutil -v -addstore Root `cygpath -w geotrustglobal.pem`"
119
+
120
+ step "Installing Usertrust Network CA cert"
121
+ create_remote_file(host, "usertrust-network.pem", USERTRUST_NETWORK_CA)
122
+ on host, "chmod 644 usertrust-network.pem"
123
+ on host, "cmd /c certutil -v -addstore Root `cygpath -w usertrust-network.pem`"
124
+
125
+ step "Installing Equifax CA cert"
126
+ create_remote_file(host, "equifax.pem", EQUIFAX_CA)
127
+ on host, "chmod 644 equifax.pem"
128
+ on host, "cmd /c certutil -v -addstore Root `cygpath -w equifax.pem`"
129
+
130
+ step "Installing Globalsign CA cert"
131
+ create_remote_file(host, "globalsign.pem", GLOBALSIGN_CA)
132
+ on host, "chmod 644 globalsign.pem"
133
+ on host, "cmd /c certutil -v -addstore Root `cygpath -w globalsign.pem`"
134
+ on host, "cp globalsign.pem \"$(cygpath \"#{find_windows_rubygems_ssl_certs_dir(host)}\")\""
135
+ end
136
+
137
+ def find_windows_rubygems_ssl_certs_dir(host)
138
+ return unless host.platform =~ /windows/
139
+ ssl_certs_dir = File.dirname(on(host, "#{gem_command(host)} which rubygems").stdout.strip) << '/rubygems/ssl_certs'
140
+ end
141
+ end
142
+
143
+ module CommandUtils
144
+ def ruby_command(host)
145
+ "env PATH=\"#{host['privatebindir']}:${PATH}\" ruby"
146
+ end
147
+ module_function :ruby_command
148
+
149
+ def gem_command(host, type='aio')
150
+ if type == 'aio'
151
+ if host['platform'] =~ /windows/
152
+ "PATH=\"#{host['privatebindir']}:${PATH}\" cmd /c gem"
153
+ else
154
+ "PATH=\"#{host['privatebindir']}:${PATH}\" gem"
155
+ end
156
+ else
157
+ on(host, 'which gem').stdout.chomp
158
+ end
159
+ end
160
+ module_function :gem_command
13
161
  end
14
162
  end
15
163
  end
@@ -1,7 +1,7 @@
1
1
  require 'beaker-rspec/spec_helper'
2
2
  require 'beaker-rspec/helpers/serverspec'
3
-
4
3
  $LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__), 'acceptance/lib'))
4
+ require 'util'
5
5
 
6
6
  unless ENV['RS_PROVISION'] == 'no'
7
7
  install_puppet
@@ -13,15 +13,16 @@ RSpec.configure do |c|
13
13
 
14
14
  # Configure all nodes in nodeset
15
15
  c.before :suite do
16
+ extend PuppetStrings::Acceptance::CommandUtils
16
17
  hosts.each do |host|
17
18
  scp_to(host, Dir.glob('puppet-strings*.gem').first, 'puppet-strings.gem')
18
- on host, 'gem install puppet-strings.gem'
19
+ install_ca_certs(host)
20
+ on host, "#{gem_command(host)} install yard"
21
+ on host, "#{gem_command(host)} install rgen"
22
+ on host, "#{gem_command(host)} install puppet-strings.gem"
19
23
 
20
24
  scp_to(host, Dir.glob('spec/fixtures/acceptance/modules/test/pkg/username-test*.gz').first, 'test.tar.gz')
21
25
  on host, puppet('module', 'install', 'test.tar.gz')
22
-
23
- on host, 'gem install yard'
24
- on host, 'gem install rgen'
25
26
  end
26
27
  end
27
28
  end
@@ -83,7 +83,7 @@ Puppet::Type.type(:database).provide :linux do
83
83
  defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7'
84
84
  has_feature :implements_some_feature
85
85
  has_feature :some_other_feature
86
- commands foo: /usr/bin/foo
86
+ commands foo: '/usr/bin/foo'
87
87
  end
88
88
 
89
89
  Puppet::Type.newtype(:database) do
@@ -111,7 +111,30 @@ SOURCE
111
111
  end
112
112
  end
113
113
 
114
- describe 'parsing a class with a typed parameter that also has a @param tag type' do
114
+ describe 'parsing a class with a typed parameter that also has a @param tag type which matches' do
115
+ let(:source) { <<-SOURCE
116
+ # A simple foo class.
117
+ # @param [Integer] param1 First param.
118
+ # @param param2 Second param.
119
+ # @param param3 Third param.
120
+ class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {
121
+ file { '/tmp/foo':
122
+ ensure => present
123
+ }
124
+ }
125
+ SOURCE
126
+ }
127
+
128
+ it 'should respect the type that was documented' do
129
+ expect{ subject }.to output('').to_stdout_from_any_process
130
+ expect(subject.size).to eq(1)
131
+ tags = subject.first.tags(:param)
132
+ expect(tags.size).to eq(3)
133
+ expect(tags[0].types).to eq(['Integer'])
134
+ end
135
+ end
136
+
137
+ describe 'parsing a class with a typed parameter that also has a @param tag type which does not match' do
115
138
  let(:source) { <<-SOURCE
116
139
  # A simple foo class.
117
140
  # @param [Boolean] param1 First param.
@@ -126,7 +149,7 @@ SOURCE
126
149
  }
127
150
 
128
151
  it 'should output a warning' do
129
- expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param1' should not contain a type specification near \(stdin\):5: ignoring in favor of parameter type information\./).to_stdout_from_any_process
152
+ expect{ subject }.to output(/\[warn\]: The type of the @param tag for parameter 'param1' does not match the parameter type specification near \(stdin\):5: ignoring in favor of parameter type information./).to_stdout_from_any_process
130
153
  end
131
154
  end
132
155
 
@@ -152,4 +175,43 @@ SOURCE
152
175
  expect(tags[1].types).to eq(['Boolean'])
153
176
  end
154
177
  end
178
+
179
+ describe 'parsing a class with a summary' do
180
+ context 'when the summary has fewer than 140 characters' do
181
+ let(:source) { <<-SOURCE
182
+ # A simple foo class.
183
+ # @summary A short summary.
184
+ class foo() {
185
+ file { '/tmp/foo':
186
+ ensure => present
187
+ }
188
+ }
189
+ SOURCE
190
+ }
191
+
192
+ it 'should parse the summary' do
193
+ expect{ subject }.to output('').to_stdout_from_any_process
194
+ expect(subject.size).to eq(1)
195
+ summary = subject.first.tags(:summary)
196
+ expect(summary.first.text).to eq('A short summary.')
197
+ end
198
+ end
199
+
200
+ context 'when the summary has more than 140 characters' do
201
+ let(:source) { <<-SOURCE
202
+ # A simple foo class.
203
+ # @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!!
204
+ class foo() {
205
+ file { '/tmp/foo':
206
+ ensure => present
207
+ }
208
+ }
209
+ SOURCE
210
+ }
211
+
212
+ it 'should log a warning' do
213
+ expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_class 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
214
+ end
215
+ end
216
+ end
155
217
  end
@@ -111,7 +111,30 @@ SOURCE
111
111
  end
112
112
  end
113
113
 
114
- describe 'parsing a defined type with a typed parameter that also has a @param tag type' do
114
+ describe 'parsing a defined type with a typed parameter that also has a @param tag type which matches' do
115
+ let(:source) { <<-SOURCE
116
+ # A simple foo defined type.
117
+ # @param [Integer] param1 First param.
118
+ # @param param2 Second param.
119
+ # @param param3 Third param.
120
+ define foo(Integer $param1, $param2, String $param3 = hi) {
121
+ file { '/tmp/foo':
122
+ ensure => present
123
+ }
124
+ }
125
+ SOURCE
126
+ }
127
+
128
+ it 'should respect the type that was documented' do
129
+ expect{ subject }.to output('').to_stdout_from_any_process
130
+ expect(subject.size).to eq(1)
131
+ tags = subject.first.tags(:param)
132
+ expect(tags.size).to eq(3)
133
+ expect(tags[0].types).to eq(['Integer'])
134
+ end
135
+ end
136
+
137
+ describe 'parsing a defined type with a typed parameter that also has a @param tag type which does not match' do
115
138
  let(:source) { <<-SOURCE
116
139
  # A simple foo defined type.
117
140
  # @param [Boolean] param1 First param.
@@ -126,7 +149,7 @@ SOURCE
126
149
  }
127
150
 
128
151
  it 'should output a warning' do
129
- expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param1' should not contain a type specification near \(stdin\):5: ignoring in favor of parameter type information\./).to_stdout_from_any_process
152
+ expect{ subject }.to output(/\[warn\]: The type of the @param tag for parameter 'param1' does not match the parameter type specification near \(stdin\):5: ignoring in favor of parameter type information./).to_stdout_from_any_process
130
153
  end
131
154
  end
132
155
 
@@ -152,4 +175,50 @@ SOURCE
152
175
  expect(tags[1].types).to eq(['Boolean'])
153
176
  end
154
177
  end
178
+
179
+ describe 'parsing a defined type with a summary' do
180
+
181
+ context 'when the summary has fewer than 140 characters' do
182
+ let(:source) { <<-SOURCE
183
+ # A simple foo defined type.
184
+ # @summary A short summary.
185
+ # @param param1 First param.
186
+ # @param [Boolean] param2 Second param.
187
+ # @param param3 Third param.
188
+ define foo(Integer $param1, $param2, String $param3 = hi) {
189
+ file { '/tmp/foo':
190
+ ensure => present
191
+ }
192
+ }
193
+ SOURCE
194
+ }
195
+
196
+ it 'should parse the summary' do
197
+ expect{ subject }.to output('').to_stdout_from_any_process
198
+ expect(subject.size).to eq(1)
199
+ summary = subject.first.tags(:summary)
200
+ expect(summary.first.text).to eq('A short summary.')
201
+ end
202
+ end
203
+
204
+ context 'when the summary has more than 140 characters' do
205
+ let(:source) { <<-SOURCE
206
+ # A simple foo defined type.
207
+ # @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!!
208
+ # @param param1 First param.
209
+ # @param [Boolean] param2 Second param.
210
+ # @param param3 Third param.
211
+ define foo(Integer $param1, $param2, String $param3 = hi) {
212
+ file { '/tmp/foo':
213
+ ensure => present
214
+ }
215
+ }
216
+ SOURCE
217
+ }
218
+
219
+ it 'should log a warning' do
220
+ expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_defined_type 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
221
+ end
222
+ end
223
+ end
155
224
  end
@@ -115,7 +115,29 @@ SOURCE
115
115
  end
116
116
  end
117
117
 
118
- describe 'parsing a function with a typed parameter that also has a @param tag type' do
118
+ describe 'parsing a function with a typed parameter that also has a @param tag type which matches' do
119
+ let(:source) { <<-SOURCE
120
+ # A simple foo function.
121
+ # @param [Integer] param1 First param.
122
+ # @param param2 Second param.
123
+ # @param param3 Third param.
124
+ # @return [Undef] Returns nothing.
125
+ function foo(Integer $param1, $param2, String $param3 = hi) {
126
+ notice 'hello world'
127
+ }
128
+ SOURCE
129
+ }
130
+
131
+ it 'should respect the type that was documented' do
132
+ expect{ subject }.to output('').to_stdout_from_any_process
133
+ expect(subject.size).to eq(1)
134
+ tags = subject.first.tags(:param)
135
+ expect(tags.size).to eq(3)
136
+ expect(tags[0].types).to eq(['Integer'])
137
+ end
138
+ end
139
+
140
+ describe 'parsing a function with a typed parameter that also has a @param tag type which does not match' do
119
141
  let(:source) { <<-SOURCE
120
142
  # A simple foo function.
121
143
  # @param [Boolean] param1 First param.
@@ -129,7 +151,7 @@ SOURCE
129
151
  }
130
152
 
131
153
  it 'should output a warning' do
132
- expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param1' should not contain a type specification near \(stdin\):6: ignoring in favor of parameter type information\./).to_stdout_from_any_process
154
+ expect{ subject }.to output(/\[warn\]: The type of the @param tag for parameter 'param1' does not match the parameter type specification near \(stdin\):6: ignoring in favor of parameter type information./).to_stdout_from_any_process
133
155
  end
134
156
  end
135
157
 
@@ -238,4 +260,41 @@ SOURCE
238
260
  expect(tags[0].types).to eq(['Any'])
239
261
  end
240
262
  end
263
+
264
+ describe 'parsing a function with a summary' do
265
+ context 'when the summary has fewer than 140 characters' do
266
+ let(:source) { <<-SOURCE
267
+ # A simple foo function.
268
+ # @summary A short summary.
269
+ # @return [String] foo
270
+ function foo() {
271
+ notice 'hello world'
272
+ }
273
+ SOURCE
274
+ }
275
+
276
+ it 'should parse the summary' do
277
+ expect{ subject }.to output('').to_stdout_from_any_process
278
+ expect(subject.size).to eq(1)
279
+ summary = subject.first.tags(:summary)
280
+ expect(summary.first.text).to eq('A short summary.')
281
+ end
282
+ end
283
+
284
+ context 'when the summary has more than 140 characters' do
285
+ let(:source) { <<-SOURCE
286
+ # A simple foo function.
287
+ # @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!!
288
+ function foo() {
289
+ notice 'hello world'
290
+ }
291
+
292
+ SOURCE
293
+ }
294
+
295
+ it 'should log a warning' do
296
+ expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_function 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
297
+ end
298
+ end
299
+ end
241
300
  end
@@ -654,4 +654,43 @@ end
654
654
  expect{ subject }.to output(/\[warn\]: The docstring for Puppet 4.x function 'foo' contains @return tags near \(stdin\):3: return value documentation should be made on the dispatch call\./).to_stdout_from_any_process
655
655
  end
656
656
  end
657
+
658
+ describe 'parsing a function with a summary' do
659
+ context 'when the summary has fewer than 140 characters' do
660
+ let(:source) { <<-SOURCE
661
+ # An example 4.x function.
662
+ # @summary A short summary.
663
+ Puppet::Functions.create_function(:foo) do
664
+ # @return [Undef]
665
+ dispatch :foo do
666
+ end
667
+ end
668
+ SOURCE
669
+ }
670
+
671
+ it 'should parse the summary' do
672
+ expect{ subject }.to output('').to_stdout_from_any_process
673
+ expect(subject.size).to eq(1)
674
+ summary = subject.first.tags(:summary)
675
+ expect(summary.first.text).to eq('A short summary.')
676
+ end
677
+ end
678
+
679
+ context 'when the summary has more than 140 characters' do
680
+ let(:source) { <<-SOURCE
681
+ # An example 4.x function.
682
+ # @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!!
683
+ Puppet::Functions.create_function(:foo) do
684
+ # @return [Undef]
685
+ dispatch :foo do
686
+ end
687
+ end
688
+ SOURCE
689
+ }
690
+
691
+ it 'should log a warning' do
692
+ expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_function 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
693
+ end
694
+ end
695
+ end
657
696
  end
@@ -105,4 +105,35 @@ SOURCE
105
105
  expect(object.commands).to eq({'foo' => '/usr/bin/foo'})
106
106
  end
107
107
  end
108
+
109
+ describe 'parsing a provider with a summary' do
110
+ context 'when the summary has fewer than 140 characters' do
111
+ let(:source) { <<-SOURCE
112
+ Puppet::Type.type(:custom).provide :linux do
113
+ @doc = '@summary A short summary.'
114
+ end
115
+ SOURCE
116
+ }
117
+
118
+ it 'should parse the summary' do
119
+ expect{ subject }.to output('').to_stdout_from_any_process
120
+ expect(subject.size).to eq(1)
121
+ summary = subject.first.tags(:summary)
122
+ expect(summary.first.text).to eq('A short summary.')
123
+ end
124
+ end
125
+
126
+ context 'when the summary has more than 140 characters' do
127
+ let(:source) { <<-SOURCE
128
+ Puppet::Type.type(:custom).provide :linux do
129
+ @doc = '@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!!'
130
+ end
131
+ SOURCE
132
+ }
133
+
134
+ it 'should log a warning' do
135
+ expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_provider 'linux' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
136
+ end
137
+ end
138
+ end
108
139
  end
@@ -235,4 +235,35 @@ SOURCE
235
235
  expect(object.parameters[0].isnamevar).to eq(true)
236
236
  end
237
237
  end
238
+
239
+ describe 'parsing a type with a summary' do
240
+ context 'when the summary has fewer than 140 characters' do
241
+ let(:source) { <<-SOURCE
242
+ Puppet::Type.newtype(:database) do
243
+ @doc = '@summary A short summary.'
244
+ end
245
+ SOURCE
246
+ }
247
+
248
+ it 'should parse the summary' do
249
+ expect{ subject }.to output('').to_stdout_from_any_process
250
+ expect(subject.size).to eq(1)
251
+ summary = subject.first.tags(:summary)
252
+ expect(summary.first.text).to eq('A short summary.')
253
+ end
254
+ end
255
+
256
+ context 'when the summary has more than 140 characters' do
257
+ let(:source) { <<-SOURCE
258
+ Puppet::Type.newtype(:database) do
259
+ @doc = '@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!!'
260
+ end
261
+ SOURCE
262
+ }
263
+
264
+ it 'should log a warning' do
265
+ expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_type 'database' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
266
+ end
267
+ end
268
+ end
238
269
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: puppet-strings
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.0.0
4
+ version: 1.1.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Puppet Inc.
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2016-11-28 00:00:00.000000000 Z
11
+ date: 2017-03-20 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: yard
@@ -41,6 +41,7 @@ files:
41
41
  - Gemfile
42
42
  - JSON.md
43
43
  - LICENSE
44
+ - MAINTAINERS
44
45
  - README.md
45
46
  - Rakefile
46
47
  - lib/puppet-strings.rb
@@ -58,6 +59,7 @@ files:
58
59
  - lib/puppet-strings/yard/code_objects/provider.rb
59
60
  - lib/puppet-strings/yard/code_objects/type.rb
60
61
  - lib/puppet-strings/yard/handlers.rb
62
+ - lib/puppet-strings/yard/handlers/helpers.rb
61
63
  - lib/puppet-strings/yard/handlers/puppet/base.rb
62
64
  - lib/puppet-strings/yard/handlers/puppet/class_handler.rb
63
65
  - lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb
@@ -73,6 +75,7 @@ files:
73
75
  - lib/puppet-strings/yard/tags/overload_tag.rb
74
76
  - lib/puppet-strings/yard/tags/parameter_directive.rb
75
77
  - lib/puppet-strings/yard/tags/property_directive.rb
78
+ - lib/puppet-strings/yard/tags/summary_tag.rb
76
79
  - lib/puppet-strings/yard/templates/default/fulldoc/html/css/common.css
77
80
  - lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_class.erb
78
81
  - lib/puppet-strings/yard/templates/default/fulldoc/html/full_list_puppet_defined_type.erb
@@ -87,28 +90,33 @@ files:
87
90
  - lib/puppet-strings/yard/templates/default/puppet_class/html/overview.erb
88
91
  - lib/puppet-strings/yard/templates/default/puppet_class/html/setup.rb
89
92
  - lib/puppet-strings/yard/templates/default/puppet_class/html/source.erb
93
+ - lib/puppet-strings/yard/templates/default/puppet_class/html/summary.erb
90
94
  - lib/puppet-strings/yard/templates/default/puppet_defined_type/html/box_info.erb
91
95
  - lib/puppet-strings/yard/templates/default/puppet_defined_type/html/header.erb
92
96
  - lib/puppet-strings/yard/templates/default/puppet_defined_type/html/overview.erb
93
97
  - lib/puppet-strings/yard/templates/default/puppet_defined_type/html/setup.rb
94
98
  - lib/puppet-strings/yard/templates/default/puppet_defined_type/html/source.erb
99
+ - lib/puppet-strings/yard/templates/default/puppet_defined_type/html/summary.erb
95
100
  - lib/puppet-strings/yard/templates/default/puppet_function/html/box_info.erb
96
101
  - lib/puppet-strings/yard/templates/default/puppet_function/html/header.erb
97
102
  - lib/puppet-strings/yard/templates/default/puppet_function/html/overview.erb
98
103
  - lib/puppet-strings/yard/templates/default/puppet_function/html/setup.rb
99
104
  - lib/puppet-strings/yard/templates/default/puppet_function/html/source.erb
105
+ - lib/puppet-strings/yard/templates/default/puppet_function/html/summary.erb
100
106
  - lib/puppet-strings/yard/templates/default/puppet_provider/html/box_info.erb
101
107
  - lib/puppet-strings/yard/templates/default/puppet_provider/html/collection.erb
102
108
  - lib/puppet-strings/yard/templates/default/puppet_provider/html/features.erb
103
109
  - lib/puppet-strings/yard/templates/default/puppet_provider/html/header.erb
104
110
  - lib/puppet-strings/yard/templates/default/puppet_provider/html/overview.erb
105
111
  - lib/puppet-strings/yard/templates/default/puppet_provider/html/setup.rb
112
+ - lib/puppet-strings/yard/templates/default/puppet_provider/html/summary.erb
106
113
  - lib/puppet-strings/yard/templates/default/puppet_type/html/box_info.erb
107
114
  - lib/puppet-strings/yard/templates/default/puppet_type/html/features.erb
108
115
  - lib/puppet-strings/yard/templates/default/puppet_type/html/header.erb
109
116
  - lib/puppet-strings/yard/templates/default/puppet_type/html/overview.erb
110
117
  - lib/puppet-strings/yard/templates/default/puppet_type/html/parameters.erb
111
118
  - lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb
119
+ - lib/puppet-strings/yard/templates/default/puppet_type/html/summary.erb
112
120
  - lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb
113
121
  - lib/puppet-strings/yard/templates/default/tags/setup.rb
114
122
  - lib/puppet-strings/yard/util.rb
@@ -161,7 +169,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
161
169
  requirements:
162
170
  - puppet, >= 3.7.0
163
171
  rubyforge_project:
164
- rubygems_version: 2.2.3
172
+ rubygems_version: 2.5.1
165
173
  signing_key:
166
174
  specification_version: 4
167
175
  summary: Puppet documentation via YARD