Open alexjfisher opened 2 years ago
I ran into the same issue with puppet's hiera
(4.x) and yaml_data
functions. To workaround the issue, add a blank line between the require
statement and the start of the comments. To repro:
$ rbenv shell 3.1.1
$ git checkout https://github.com/puppetlabs/puppet
$ echo 'gem "puppet-strings"' >> Gemfile.local
$ bundle install
...
$ bundle exec puppet strings generate --format json --out /tmp/strings.json
...
Note the abs
function is documented as expected:
$ jq -r '.puppet_functions[] | select(.name == "abs").docstring.text ' /tmp/strings.json | head
Returns the absolute value of a Numeric value, for example -34.56 becomes
34.56. Takes a single `Integer` or `Float` value as an argument.
*Deprecated behavior*
For backwards compatibility reasons this function also works when given a
number in `String` format such that it first attempts to covert it to either a `Float` or
an `Integer` and then taking the absolute value of the result. Only strings representing
a number in decimal format is supported - an error is raised if
value is not decimal (using base 10). Leading 0 chars in the string
But yaml_data
is not:
$ jq -r '.puppet_functions[] | select(.name == "yaml_data").docstring.text ' /tmp/strings.json | head
Note the source https://github.com/puppetlabs/puppet/blob/8.8.0/lib/puppet/functions/yaml_data.rb#L3-L9 doesn't contain a blank line between the require
and comments.
Adding one blank line resolves the issue:
$ sed -iE 's/require .yaml./&\n/' lib/puppet/functions/yaml_data.rb
$ bundle exec puppet strings generate --format json --out /tmp/strings.json
$ jq -r '.puppet_functions[] | select(.name == "yaml_data").docstring.text ' /tmp/strings.json | head
The `yaml_data` is a hiera 5 `data_hash` data provider function.
See [the configuration guide documentation](https://puppet.com/docs/puppet/latest/hiera_config_yaml_5.html#configuring-a-hierarchy-level-built-in-backends) for
how to use this function.
I've noticed that when generating reference documentation for stdlib, the version of ruby used changes the output. Specifically, the documentation for
to_yaml
andto_json
doesn't get generated with Ruby 2.7 but does when using Ruby 2.5. (Puppet Strings 2.9.0 in both cases)No other functions in stdlib are affected. There appears to be an issue with having any code before the documentation comments. In these functions, this is a
require 'yaml'
andrequire 'json'
respectively. I could easily workaround the issue by moving this code into the function dispatches, but the change of behaviour between Ruby versions makes me think it's worth raising this as a bug here.