search

puppetlabs / puppet-strings

The next generation Puppet documentation extraction and presentation tool.
http://puppetlabs.github.io/puppet-strings/
Apache License 2.0
90 stars 84 forks source link

Use tilde heredocs for readability #317

Closed danielparks closed 2 years ago

danielparks commented 2 years ago

This changes most heredocs to use the tilde syntax with variable interpolation off. It indents the contents of the heredoc along with the final symbol.

To maintain these changes, it enables Layout/HeredocIndentation and Layout/ClosingHeredocIndentation in Rubocop.

The tilde syntax smartly strips the indentation, and allows for different indention of the closing identifier:

"test\n" == <<~'END'
    test
  END

This syntax was introduced in Ruby 2.3.0, so this will not pose compatibility problems.

danielparks commented 2 years ago

Updated the tests to work and added lengthy comments (maybe I shouldn’t wrap at 80 characters?).

I also updated the commit message in hope that it will help some future fool:

Tests that should fail

Note that two tests couldn’t be updated to a more common heredoc format to avoid failing.

It appears there is a problem with the way YARD parses parameters with defaults with a heredoc (YARD #779). There is a work-around for that issue in PuppetStrings::Yard::Handlers::Ruby::Base, but it can’t work in these cases because YARD doesn’t provide enough source to read the whole heredoc content.

Given that these are tests of the Puppet 3 style functions, it’s probably not worth pursuing this issue.

As I said, I’m inclined to ignore this, even though it pains me deep inside.

chelnak commented 2 years ago

@danielparks Might be worth rebasing this PR when you get five minutes. Then we can merge it.

chelnak commented 2 years ago

💯 @danielparks 💯