(PUP-12063) Merge osp-docs changes back to puppet

Pull in changes that were made in osp-docs

puppetlabs/osp-docs@f24d9b3
puppetlabs/osp-docs@c3fec14
puppetlabs/osp-docs@27fa002
puppetlabs/osp-docs@27fa002
puppetlabs/osp-docs@f8fc805
puppetlabs/osp-docs@4a448c8
puppetlabs/osp-docs@1914d58
puppetlabs/osp-docs@e1b7ffa

Author: joshcooper

lib/puppet/application/apply.rb

@@ -58,6 +58,11 @@ def help
         [--catalog <catalog>] [--write-catalog-summary] <file>
 
 
+      EXAMPLE
+      -------
+          $ puppet apply -e 'notify { "hello world": }'
+
+
       DESCRIPTION
       -----------
       This is the standalone puppet execution tool; use it to apply

lib/puppet/application/ssl.rb

@@ -57,13 +57,13 @@ def help
       * submit_request:
         Generate a certificate signing request (CSR) and submit it to the CA. If
         a private and public key pair already exist, they will be used to generate
-        the CSR. Otherwise a new key pair will be generated. If a CSR has already
+        the CSR. Otherwise, a new key pair will be generated. If a CSR has already
         been submitted with the given `certname`, then the operation will fail.
 
       * generate_request:
-        Generate a certificate signing request (CSR). If
-        a private and public key pair already exist, they will be used to generate
-        the CSR. Otherwise a new key pair will be generated.
+        Generate a certificate signing request (CSR). If a private and public key
+        pair exist, they will be used to generate the CSR. Otherwise a new key
+        pair will be generated.
 
       * download_cert:
         Download a certificate for this host. If the current private key matches

lib/puppet/defaults.rb

@@ -161,8 +161,9 @@ def self.initialize_default_settings!(settings)
     :skip_logging_catalog_request_destination => {
       :default => false,
       :type    => :boolean,
-      :desc    => "If you wish to suppress the notice of which compiler supplied the
-        catalog",
+      :desc    => "Disables \"notice\" level messages specifying which server the
+        agent requests a catalog from and which server actually handles
+        the request.",
     },
     :merge_dependency_warnings => {
       :default => false,

lib/puppet/functions/find_file.rb

@@ -7,6 +7,10 @@
 # directory. (For example, the reference `mysql/mysqltuner.pl` will search for the
 # file `<MODULES DIRECTORY>/mysql/files/mysqltuner.pl`.)
 #
+# If this function is run via puppet agent, it checks for file existence on the
+# Puppet Primary server. If run via puppet apply, it checks on the local host.
+# In both cases, the check is performed before any resources are changed.
+#
 # This function can also accept:
 #
 # * An absolute String path, which checks for the existence of a file from anywhere on disk.

lib/puppet/functions/lookup.rb

@@ -97,7 +97,7 @@
 # or `{'strategy' => 'hash'}` --- Same as the string versions of these merge behaviors.
 # * `{'strategy' => 'deep', <DEEP OPTION> => <VALUE>, ...}` --- Same as `'deep'`,
 # but can adjust the merge with additional options. The available options are:
-#     * `'knockout_prefix'` (string or undef) --- A string prefix to indicate a
+#     * `'knockout_prefix'` (string) --- A string prefix to indicate a
 #     value should be _removed_ from the final result. If a value is exactly equal
 #     to the prefix, it will knockout the entire element. Defaults to `undef`, which
 #     disables this feature.

lib/puppet/functions/new.rb

@@ -557,7 +557,7 @@
 # @example Simple Conversion to String specifying the format for the given value directly
 #
 # ```puppet
-# $str = String(10, "%#x")    # produces '0x10'
+# $str = String(10, "%#x")    # produces '0xa'
 # $str = String([10], "%(a")  # produces '("10")'
 # ```
 #