Unbreak rake strings:generate:reference
#1239
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
bastelfreak
reviewed
Apr 28, 2022
bastelfreak
reviewed
Apr 28, 2022
ekohl
reviewed
Apr 28, 2022
Comment on lines
+9
to
10
| This function will return | ||
| the first value in a list of values that is not undefined or an empty string. |
There was a problem hiding this comment.
Perhaps even shorten it to "Return the first ..."?
There was a problem hiding this comment.
I tried to use the same phrasing as used in the other functions (they start with "This function"). It is not very consistent so maybe somebody will step-in to improve phrasing and consistency. As a non-native English speaker, I do not feel confident for such a task 😨
Broken how? It was working for me yesterday (not withstanding puppetlabs/puppet-strings#296) |
|
+1 for fixing all the warnings though! :) |
|
"Broken" in this way: romain@desktop-fln40kq ~/Projects/puppetlabs/puppetlabs-stdlib % echo Moin > REFERENCE.md
romain@desktop-fln40kq ~/Projects/puppetlabs/puppetlabs-stdlib % bundle exec rake strings:generate:reference
[warn]: Missing @return tag near functions/ensure.pp:2.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Fqdn' at types/fqdn.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Host' at types/host.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Port' at types/port.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Yes_no' at types/yes_no.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::HTTPUrl' at types/httpurl.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Datasize' at types/datasize.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::HTTPSUrl' at types/httpsurl.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Port::User' at types/port/user.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::HttpStatus' at types/httpstatus.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::IP::Address' at types/ip/address.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Compat::Ipv6' at types/compat/ipv6.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Ensure::File' at types/ensure/file.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::ObjectStore' at types/objectstore.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Windowspath' at types/windowspath.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Port::Dynamic' at types/port/dynamic.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::IP::Address::V4' at types/ip/address/v4.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::IP::Address::V6' at types/ip/address/v6.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Ensure::Service' at types/ensure/service.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Port::Ephemeral' at types/port/ephemeral.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Syslogfacility' at types/syslogfacility.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Port::Privileged' at types/port/privileged.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Port::Registered' at types/port/registered.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Ensure::File::File' at types/ensure/file/file.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Ensure::File::Link' at types/ensure/file/link.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Compat::Ip_address' at types/compat/ip_address.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::ObjectStore::GSUri' at types/objectstore/gsuri.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::ObjectStore::S3Uri' at types/objectstore/s3uri.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Port::Unprivileged' at types/port/unprivileged.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::IP::Address::V6::Full' at types/ip/address/v6/full.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::IP::Address::Nosubnet' at types/ip/address/nosubnet.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Ensure::File::Directory' at types/ensure/file/directory.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::IP::Address::V6::Nosubnet' at types/ip/address/v6/nosubnet.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::IP::Address::V6::Compressed' at types/ip/address/v6/compressed.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::IP::Address::V6::Nosubnet::Full' at types/ip/address/v6/nosubnet/full.pp:1.
[warn]: Missing documentation for Puppet type alias 'Stdlib::IP::Address::V6::Nosubnet::Compressed' at types/ip/address/v6/nosubnet/compressed.pp:1.
[warn]: Missing @return tag near lib/puppet/functions/to_ruby.rb:18.
[warn]: Missing @return tag near lib/puppet/functions/to_python.rb:18.
[warn]: The docstring for Puppet 4.x function 'parsehocon' contains @return tags near lib/puppet/functions/parsehocon.rb:13: return value documentation should be made on the dispatch call.
[warn]: Missing @return tag near lib/puppet/functions/parsehocon.rb:16.
[warn]: Missing documentation for Puppet function 'pw_hash' at lib/puppet/parser/functions/pw_hash.rb:6.
[warn]: Missing @return tag near lib/puppet/parser/functions/pw_hash.rb:6.
[warn]: Missing documentation for Puppet function 'getparam' at lib/puppet/parser/functions/getparam.rb:6.
[warn]: Missing @return tag near lib/puppet/parser/functions/getparam.rb:6.
[warn]: Missing documentation for Puppet function 'fqdn_rotate' at lib/puppet/parser/functions/fqdn_rotate.rb:6.
[warn]: Missing @return tag near lib/puppet/parser/functions/fqdn_rotate.rb:6.
[warn]: Missing documentation for Puppet function 'seeded_rand' at lib/puppet/parser/functions/seeded_rand.rb:6.
[warn]: Missing @return tag near lib/puppet/parser/functions/seeded_rand.rb:6.
[warn]: Missing documentation for Puppet function 'ensure_resource' at lib/puppet/parser/functions/ensure_resource.rb:6.
[warn]: Missing @return tag near lib/puppet/parser/functions/ensure_resource.rb:6.
[warn]: Missing documentation for Puppet function 'ensure_resources' at lib/puppet/parser/functions/ensure_resources.rb:5.
[warn]: Missing @return tag near lib/puppet/parser/functions/ensure_resources.rb:5.
[warn]: Missing documentation for Puppet function 'fqdn_rand_string' at lib/puppet/parser/functions/fqdn_rand_string.rb:3.
[warn]: Missing @return tag near lib/puppet/parser/functions/fqdn_rand_string.rb:3.
[warn]: Missing documentation for Puppet function 'defined_with_params' at lib/puppet/parser/functions/defined_with_params.rb:6.
[warn]: Missing @return tag near lib/puppet/parser/functions/defined_with_params.rb:6.
[warn]: The length of the summary for puppet_function 'validate_x509_rsa_key_pair' exceeds the recommended limit of 140 characters.
[warn]: The length of the summary for puppet_function 'validate_slength' exceeds the recommended limit of 140 characters.
[warn]: Missing documentation for Puppet function 'try_get_value' at lib/puppet/parser/functions/try_get_value.rb:7.
[warn]: Missing @return tag near lib/puppet/parser/functions/try_get_value.rb:7.
[warn]: Invalid tag format for @example in file `lib/puppet/parser/functions/round.rb` near line 7
[warn]: Missing documentation for Puppet function 'dig44' at lib/puppet/parser/functions/dig44.rb:7.
[warn]: Missing @return tag near lib/puppet/parser/functions/dig44.rb:7.
[warn]: The length of the summary for puppet_function 'pick' exceeds the recommended limit of 140 characters.
Files: 249
Modules: 4 ( 0 undocumented)
Classes: 1 ( 0 undocumented)
Constants: 0 ( 0 undocumented)
Attributes: 1 ( 0 undocumented)
Methods: 3 ( 0 undocumented)
Puppet Classes: 2 ( 0 undocumented)
Puppet Data Types: 0 ( 0 undocumented)
Puppet Data Type Aliases: 57 ( 35 undocumented)
Puppet Defined Types: 0 ( 0 undocumented)
Puppet Types: 2 ( 0 undocumented)
Puppet Providers: 1 ( 0 undocumented)
Puppet Functions: 183 ( 7 undocumented)
Puppet Tasks: 0 ( 0 undocumented)
Puppet Plans: 0 ( 0 undocumented)
83.46% documented
romain@desktop-fln40kq ~/Projects/puppetlabs/puppetlabs-stdlib % echo $?
1
romain@desktop-fln40kq ~/Projects/puppetlabs/puppetlabs-stdlib % cat REFERENCE.md
MoinThis is with ruby 2.7.4 packaged in Debian. A spot a few issues and am working on it. |
smortex
force-pushed
the
unbreak-rake-reference
branch
from
6f80229
to
de96030
Compare
|
I updated the PR and added an updated REFERENCE.md which helps review IMHO 😉 |
|
@smortex The added documentation fixes and the updated reference.md all look good to me. |
[warn]: Missing documentation for Puppet function 'foo' at lib/puppet/parser/functions/foo.rb:42 [warn]: Missing @return tag near lib/puppet/parser/functions/foo.rb:42
They must be at the dispatch call.
[warn]: Missing @return tag near lib/puppet/functions/foo.rb:42.
[warn]: Invalid tag format for @example in file `lib/puppet/parser/functions/foo.rb` near line 42
[warn]: The length of the summary for puppet_function 'foo' exceeds the recommended limit of 140 characters.
[warn]: Missing documentation for Puppet type alias 'Stdlib::Forr' at types/foo.pp:1.
smortex
force-pushed
the
unbreak-rake-reference
branch
from
de96030
to
75eb48f
Compare
|
Opened puppetlabs/puppetlabs_spec_helper#352 to enhance validation and removed the corresponding code. I rebased on top of master (and fixed more issues), but now rubocop insists to see a comma after the last parameter of a multiline method call, but this break puppet-string 🙃 😒 |
puppet-strings choke on heredoc start tags followed by a comma. Because rubocop ensures a comma is present after the last parameter of a multiline method call, change these calls to in-line calls so that we do not cause issue with puppet-strings nor with rubocop.
bastelfreak
approved these changes
Jun 1, 2022
ekohl
approved these changes
Jun 1, 2022
| @@ -370,6 +354,19 @@ class { 'stdlib::manage': | |||
| } | |||
| ``` | |||
|
|
|||
| ##### | |||
There was a problem hiding this comment.
It would be nice to have a title for this, but it looks like other examples lack one too.
| @@ -370,6 +354,19 @@ class { 'stdlib::manage': | |||
| } | |||
| ``` | |||
|
|
|||
| ##### | |||
|
|
|||
| ```puppet | |||
There was a problem hiding this comment.
Shame puppet-strings lacks YAML examples
david22swan
approved these changes
Jun 6, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
rake strings:generate:referencecurrently fail and does not updateREFERENCE.md.This PR update the GitHub actions to check that the documentation build correctly and fix the issues preventing it for working.