Broken function documentation when using newer rubies and function contains any code before documentation

[alexjfisher]

I've noticed that when generating reference documentation for stdlib, the version of ruby used changes the output.
Specifically, the documentation for to_yaml and to_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' and require '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.

[joshcooper]

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.