Fix capitalize docs
Fix capitalize docs

Capitalize lower-cases the remaining characters (due to the Ruby function having this behavior); document this, and make minor wording tweaks.
DavidS/puppetlabs-stdlib,fuel-infra/puppetlabs-stdlib,puppetlabs/puppetlabs-stdlib,yadavnikhil/puppetlabs-stdlib,jbondpdx/puppetlabs-stdlib,HelenCampbell/puppetlabs-stdlib