puppet-strings 1.0.0 → 1.1.0

Sign up to get free protection for your applications and to get access to all the features.
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