(maint) Instead of two indent-stripping methods, let's have one

This was unDRY, AND the methods had differing behavior. (The faces one didn't
make exceptions for first-line underhang, which demanded unintuitive source
formatting.)

This commit just replaces the implementation of the faces scrubber with a
scrub() call.

Spec test change: This method trims trailing newlines from strings.
(maint) Refactor Puppet::Util::Docs.scrub

It was hard to understand what this method was doing, and once I got it, I
noticed it wasn't quite doing what it claimed. (It was cheating -- grabbing the
indent of the second line with text and assuming that was the least common
indent. This meant you could break it by starting a doc fragment with a line of
text, two newlines, and an indented block of example code.)

This commit replaces it with something more clear and correct, as well as some
comments explaining what we expect it to do. We also trim trailing whitespace,
while we're at it; this costs some speed, but should make it even more
reliable/useful.

We also add tests for scrub in this commit, at spec/unit/util/docs_spec.rb.
(#22489) Fix mangled setting descriptions in config reference and genconfig output

This commit:

- Makes the BaseSetting class stop mangling @desc values. This should offer a
  tiny performance win when Puppet initializes its settings, to the tune of
  about 200 gsub calls. Setting descriptions are now tainted with least-common
  hanging indentation, the same way type, parameter, property, and provider
  descriptions are; we expect anyone consuming these strings to scrub them.
- Makes genconfig scrub hanging indentation from setting descriptions. Swaps a
  few (slow) +=s for (fast) <<s.
- Makes the configuration reference scrub setting descriptions instead of
  further mangling them by deleting all linebreaks. This fixes bug #22489 and
  allows us to use block-level Markdown formatting in setting descriptions.
(maint) Adjust wrapping and indent of a bunch of setting descriptions

Since we reliably handle the hanging indent style now, we can clean up this file
a bit and stop coding these descriptions so paranoiacally. (Trivia: This might
also result in a tiny win when initializing settings, as it replaces about 50
pointless method calls with literal newlines, but it's probably not enough for
anyone to notice.)
(maint) Fix sloppy indent in schedule type
(maint) Fix docs indent breakage in yumrepo type
(maint) Reduce object creation in several string concatenations

Change += to << where applicable, and use interpolation instead of +.
(maint) Prevent possible formatting problems on indirection reference

- Use scrub to protect against indentation comedy, even though we seem fine
  at the moment.
- Adjust wonky Markdown in the foreword.
(maint) Avoid accidental outdenting when appending stuff to doc fragments

When appending:

* Value collection summaries to parameter docs
* Dochook blurbs to provider docs

...we would sometimes cause an "outdent" if the original fragment ended with a
newline. Like so:

First line
    hanging indent
    hanging indent
  appended blurb

When we ran scrub() on that fragment later, we would get the wrong amount of
space removed. This silently sorta succeeded when scrub() was being lazy about
finding least common indent, but making scrub() work as expected made any sloppy
appends break the formatting.

This commit adds some scrub calls and makes our appends more predictable. This
will result in a certain amount of double-scrubbing, but that's okay.
Merge pull request #1890 from nfagerlund/issue_22489_indent_slapstick_redux

Issue 22489: Fix mangled setting descriptions, refactor some docs-related code