(#14872) PMT respect environment's module path

This patch fixes the Puppet::ModuleTool#set_option_defaults method such that
it respects the specified environment (if any) when determining the default
value for the --target-dir (the modules install directory) option.
The patch overhauls the entire method in the process to make it more readable,
and it also updates relevant unit tests and adds a pair of new acceptance
tests.
Merge branch 'mruzicka-ticket/master/14872-PMT-respect-environments'

* mruzicka-ticket/master/14872-PMT-respect-environments:
  (#14872) PMT respect environment's module path
(yardoc) Fix mixup of 'is' vs. 'should' in Type#[](name) yardoc.

The method was documented to return the 'is' value when it should have
been the 'should' value. This commit corrects this.