(MODULES-9304) Add Puppet Strings docs

[eimlav]

No description provided.

[eimlav]

puppetlabs-acl/lib/puppet/provider/acl/windows/base.rb

Lines 17 to 21 in 76fdb70

	if Puppet::Util::Platform.windows?
	require Pathname.new(__FILE__).dirname + '../../../../' + 'puppet/type/acl/ace'
	require 'puppet/util/windows/security'
	require 'win32/security'
	end

The reason for this change is that by putting everything inside the if block, YARD is unable to parse the comments of any of the methods. I tried a number of different things to remove this if block however every time it would result in errors. By applying it only on the requires, the tests pass fine however I'm not sure if this is the best solution. Feel free to give some other ideas of better alternatives.

[RandomNoun7]

I see now that I should have commented each of these one line lower to make the review comments easier to see in this view. Sorry about that.

[glennsarti]

By applying it only on the requires, the tests pass fine however I'm not sure if this is the best solution. Feel free to give some other ideas of better alternatives.

Strictly speaking you should probably add a guard clause to every single public method e.g.

def do_something()
  raise "Only Supported on Windows" unless Puppet::Util::Platform.windows?
  ...
end

However...this whole if thing could be a hangover from the Puppet 3 days and the tests may be testing the wrong thing?

[eimlav]

@glennsarti I believe the errors are to do with Windows platform specific gem dependencies that do not work on nix based systems (i.e. the gems being required in the file). The acceptance test suite also contains similar if clauses for requiring gems from puppet/util/windows/.... For now the proposed solution appears to work in adhoc however finding a cleaner solution is something that should be investigated in the future.

[RandomNoun7]

Manually tested the module with a Puppet master deliberately trying to trigger an explosion. Even with no if clause it all, the module did not cause an error during catalog compilation, and it functioned as expected once the code ran on the Windows node.