Edits from docs team

Author: joshcooper

lib/puppet/defaults.rb

@@ -7,6 +7,7 @@ def self.default_diffargs
     '-u'
   end
 
+  # If you modify this, update puppet/type/file/checksum.rb too
   def self.default_digest_algorithm
     'sha256'
   end
@@ -161,9 +162,8 @@ def self.initialize_default_settings!(settings)
     :skip_logging_catalog_request_destination => {
       :default => false,
       :type    => :boolean,
-      :desc    => "Disables \"notice\" level messages specifying which server the
-        agent requests a catalog from and which server actually handles
-        the request.",
+      :desc => "Specifies whether to suppress the notice of which compiler
+        supplied the catalog. A value of `true` suppresses the notice.",
     },
     :merge_dependency_warnings => {
       :default => false,
@@ -418,13 +418,15 @@ def self.initialize_default_settings!(settings)
       :type     => :boolean,
       :default  => true,
       :desc     => <<-'EOT'
-      When versioned_environment_dirs is `true` Puppet will readlink the environmentpath
-      when constructing the environment's modulepath. The full readlinked path is referred
-      to as the "resolved path" and the configured path potentially containing symlinks is
-      the "configured path". When reporting where resources come from users may choose
-      between the configured or resolved path.
-
-      When set to false, the resolved paths are reported instead of the configured paths.
+      Specifies how environment paths are reported. When the value of
+      `versioned_environment_dirs` is `true`, Puppet applies the readlink function to
+      the `environmentpath` setting when constructing the environment's modulepath. The
+      full readlinked path is referred to as the "resolved path," and the configured
+      path potentially containing symlinks is the "configured path." When reporting
+      where resources come from, users may choose between the configured and resolved
+      path.
+
+      When set to `false`, the resolved paths are reported instead of the configured paths.
       EOT
     },
     :use_last_environment => {
@@ -1205,33 +1207,34 @@ def self.initialize_default_settings!(settings)
     :ca_refresh_interval => {
       :default    => "1d",
       :type       => :duration,
-      :desc       => "How often the Puppet agent refreshes its local CA certs. By
-         default the CA certs are refreshed once every 24 hours. If a different
-         duration is specified, then the agent will refresh its CA certs whenever
-         it next runs and the elapsed time since the certs were last refreshed
-         exceeds the duration.
-
-         In general, the duration should be greater than the `runinterval`.
-         Setting it to 0 or an equal or lesser value than `runinterval`,
-         will cause the CA certs to be refreshed on every run.
-
-         If the agent downloads new CA certs, the agent will use it for subsequent
+      :desc       => "How often the Puppet agent refreshes its local CA
+         certificates. By default, CA certificates are refreshed every 24 hours. If a
+         different interval is specified, the agent refreshes its CA certificates during
+         the next agent run if the elapsed time since the certificates were last
+         refreshed exceeds the specified duration.
+
+         In general, the interval should be greater than the `runinterval`
+         value. Setting the `ca_refresh_interval` value to 0 or an equal or
+         lesser value than `runinterval` causes the CA certificates to be
+         refreshed on every run.
+
+         If the agent downloads new CA certs, the agent uses those for subsequent
          network requests. If the refresh request fails or if the CA certs are
          unchanged on the server, then the agent run will continue using the
          local CA certs it already has. #{AS_DURATION}",
     },
     :crl_refresh_interval => {
       :default    => "1d",
       :type       => :duration,
-      :desc       => "How often the Puppet agent refreshes its local CRL. By
-         default the CRL is refreshed once every 24 hours. If a different
-         duration is specified, then the agent will refresh its CRL whenever
-         it next runs and the elapsed time since the CRL was last refreshed
-         exceeds the duration.
+      :desc       => "How often the Puppet agent refreshes its local Certificate
+         Revocation List (CRL). By default, the CRL is refreshed every 24 hours. If
+         a different interval is specified, the agent refreshes its CRL on the next
+         Puppet agent run if the elapsed time since the CRL was last refreshed
+         exceeds the specified interval.
 
-         In general, the duration should be greater than the `runinterval`.
-         Setting it to 0 or an equal or lesser value than `runinterval`,
-         will cause the CRL to be refreshed on every run.
+         In general, the interval should be greater than the `runinterval` value.
+         Setting the `crl_refresh_interval` value to 0 or an equal or lesser value
+         than `runinterval` causes the CRL to be refreshed on every run.
 
          If the agent downloads a new CRL, the agent will use it for subsequent
          network requests. If the refresh request fails or if the CRL is
@@ -1241,18 +1244,19 @@ def self.initialize_default_settings!(settings)
     :hostcert_renewal_interval => {
       :default => "30d",
       :type    => :duration,
-      :desc    => "When the Puppet agent refreshes its client certificate.
-         By default the client certificate will refresh 30 days before the certificate
-         expires. If a different duration is specified, then the agent will refresh its
-         client certificate whenever it next runs and if the client certificate expires
-         within the duration specified.
+      :desc => "How often the Puppet agent renews its client certificate. By
+         default, the client certificate is renewed 30 days before the certificate
+         expires. If a different interval is specified, the agent renews its client
+         certificate during the next agent run, assuming that the client certificate has
+         expired within the specified duration.
 
-         In general, the duration should be greater than the `runinterval`.
-         Setting it to 0 will disable automatic renewal.
+         In general, the `hostcert_renewal_interval` value should be greater than the
+         `runinterval` value. Setting the `hostcert_renewal_interval` value to 0 disables
+         automatic renewal.
 
-         If the agent downloads a new certificate, the agent will use it for subsequent
-         network requests. If the refresh request fails, then the agent run will continue using the
-         certificate it already has. #{AS_DURATION}",
+         If the agent downloads a new certificate, the agent will use it
+         for subsequent network requests. If the refresh request fails, the agent run
+         continues to use its existing certificate. #{AS_DURATION}",
     },
     :keylength => {
       :default    => 4096,
@@ -1493,8 +1497,10 @@ def self.initialize_default_settings!(settings)
     :exclude_unchanged_resources => {
       :default => true,
       :type => :boolean,
-      :desc => 'When set to true, resources that have had no changes after catalog application
-        will not have corresponding unchanged resource status updates listed in the report.'
+      :desc => "Specifies how unchanged resources are listed in reports. When
+        set to `true`, resources that have had no changes after catalog application
+        will not have corresponding unchanged resource status updates listed in a
+        report."
     },
     :reportdir => {
       :default => "$vardir/reports",
@@ -1746,11 +1752,12 @@ def self.initialize_default_settings!(settings)
     :allow_pson_serialization => {
       :default    => false,
       :type       => :boolean,
-      :desc       => "Whether when unable to serialize to JSON or other formats,
-        Puppet falls back to PSON. This option affects both puppetserver's
-        configuration management service responses and when the agent saves its
-        cached catalog. This option is useful in preventing the loss of data because
-        rich data cannot be serialized via PSON.",
+      :desc => "Whether to allow PSON serialization. When unable to serialize to
+        JSON or other formats, Puppet falls back to PSON. This option affects the
+        configuration management service responses of Puppet Server and the process by
+        which the agent saves its cached catalog. With a default value of `false`, this
+        option is useful in preventing the loss of data because rich data cannot be
+        serialized via PSON.",
     },
     :agent_catalog_run_lockfile => {
       :default    => "$statedir/agent_catalog_run.lock",
@@ -1776,7 +1783,7 @@ def self.initialize_default_settings!(settings)
       :type       => :boolean,
       :default    => false,
       :desc       => "Whether to include legacy facts when requesting a catalog. This
-        option can be set to false provided all puppet manifests, hiera.yaml and hiera
+        option can be set to `false` if all puppet manifests, hiera.yaml, and hiera
         configuration layers no longer access legacy facts, such as `$osfamily`, and
         instead access structured facts, such as `$facts['os']['family']`."
     },
@@ -2092,12 +2099,12 @@ def self.initialize_default_settings!(settings)
     :preprocess_deferred => {
       :default => false,
       :type => :boolean,
-      :desc => "Whether puppet should call deferred functions before applying
-        the catalog. If set to `true`, then all prerequisites needed for the
-        deferred function must be satisfied prior to puppet running. If set to
-        `false`, then deferred functions will follow puppet relationships and
-        ordering. This allows puppet to install prerequisites needed for a
-        deferred function and call the deferred function in the same run."
+      :desc => "Whether Puppet should call deferred functions before applying
+        the catalog. If set to `true`, all prerequisites required for the
+        deferred function must be satisfied before the Puppet run. If set to
+        `false`, deferred functions follow Puppet relationships and
+        ordering. In this way, Puppet can install the prerequisites required for a
+        deferred function and call the deferred function in the same run.",
     },
     :summarize => {
         :default  => false,

lib/puppet/functions/capitalize.rb

@@ -5,7 +5,7 @@
 # This function is compatible with the stdlib function with the same name.
 #
 # The function does the following:
-# * For a `String`, a string with its first character in upper case version is returned.
+# * For a `String`, a string is returned in which the first character is uppercase.
 #   This is done using Ruby system locale which handles some, but not all
 #   special international up-casing rules (for example German double-s ß is capitalized to "Ss").
 # * For an `Iterable[Variant[String, Numeric]]` (for example an `Array`) each value is capitalized and the conversion is not recursive.

lib/puppet/functions/index.rb

@@ -40,8 +40,8 @@
 # Note that the lambda gets the value and not an array with `[key, value]` as in other
 # iterative functions.
 #
-# Using a lambda that accepts two values works the same way, it simply gets the index/key
-# as the first parameter, and the value as the second.
+# Using a lambda that accepts two values works the same way. The lambda gets the index/key
+# as the first parameter and the value as the second parameter.
 #
 # @example Using the `index` function with an Array and a two-parameter lambda
 #

lib/puppet/functions/regsubst.rb

@@ -20,7 +20,7 @@
   #        - *M*         Multiline regexps
   #        - *G*         Global replacement; all occurrences of the regexp in each target string will be replaced.  Without this, only the first occurrence will be replaced.
   # @param encoding [Enum['N','E','S','U']]
-  #      Deprecated and ignored parameter, only here for compatibility.
+  #      Deprecated and ignored parameter, included only for compatibility.
   # @return [Array[String], String] The result of the substitution. Result type is the same as for the target parameter.
   # @deprecated
   #   This method has the optional encoding parameter, which is ignored.

lib/puppet/functions/unique.rb

@@ -65,8 +65,9 @@
 # *first-found* unique value, but for `Hash` it contains associations from a set of keys to the set of values clustered by the
 # equality lambda (or the default value equality if no lambda was given). This makes the `unique` function more versatile for hashes
 # in general, while requiring that the simple computation of "hash's unique set of values" is performed as `$hsh.map |$k, $v| { $v }.unique`.
-# (A unique set of hash keys is in general meaningless (since they are unique by definition) - although if processed with a different
-# lambda for equality that would be different. First map the hash to an array of its keys if such a unique computation is wanted).
+# (Generally, it's meaningless to compute the unique set of hash keys because they are unique by definition. However, the
+# situation can change if the hash keys are processed with a different lambda for equality. For this unique computation,
+# first map the hash to an array of its keys.)
 # If the more advanced clustering is wanted for one of the other data types, simply transform it into a `Hash` as shown in the
 # following example.
 #

lib/puppet/type/exec.rb

@@ -437,13 +437,12 @@ def check(value)
         actually contain `myfile`, the exec will keep running every time
         Puppet runs.
 
-        This parameter can also take an array of files and the command will
-        not run if **any** of these files exist. For example:
+        This parameter can also take an array of files, and the command will
+        not run if **any** of these files exist. Consider this example:
 
             creates => ['/tmp/file1', '/tmp/file2'],
 
-        will only run the command if both files don't exist.
-
+        The command is only run if both files don't exist.
       EOT
 
       accept_arrays

lib/puppet/type/file/checksum.rb

@@ -7,11 +7,13 @@
 Puppet::Type.type(:file).newparam(:checksum) do
   include Puppet::Util::Checksums
 
+  # The default is defined in Puppet.default_digest_algorithm
   desc "The checksum type to use when determining whether to replace a file's contents.
 
-    The default checksum type is #{Puppet.default_digest_algorithm}."
+    The default checksum type is sha256."
 
-  newvalues(*Puppet::Util::Checksums.known_checksum_types)
+  # The values are defined in Puppet::Util::Checksums.known_checksum_types
+  newvalues(:sha256, :sha256lite, :md5, :md5lite, :sha1, :sha1lite, :sha512, :sha384, :sha224, :mtime, :ctime, :none)
 
   defaultto do
     Puppet[:digest_algorithm].to_sym

lib/puppet/type/file/selcontext.rb

@@ -86,7 +86,7 @@ def sync
   end
 
   Puppet::Type.type(:file).newparam(:selinux_ignore_defaults) do
-    desc "If this is set then Puppet will not ask SELinux (via selabel_lookup) to
+    desc "If this is set, Puppet will not call the SELinux function selabel_lookup to
       supply defaults for the SELinux attributes (seluser, selrole,
       seltype, and selrange). In general, you should leave this set at its
       default and only set it to true when you need Puppet to not try to fix
@@ -99,7 +99,7 @@ def sync
   Puppet::Type.type(:file).newproperty(:seluser, :parent => Puppet::SELFileContext) do
     desc "What the SELinux user component of the context of the file should be.
       Any valid SELinux user component is accepted.  For example `user_u`.
-      If not specified it defaults to the value returned by selabel_lookup for
+      If not specified, it defaults to the value returned by selabel_lookup for
       the file, if any exists.  Only valid on systems with SELinux support
       enabled."
 
@@ -110,7 +110,7 @@ def sync
   Puppet::Type.type(:file).newproperty(:selrole, :parent => Puppet::SELFileContext) do
     desc "What the SELinux role component of the context of the file should be.
       Any valid SELinux role component is accepted.  For example `role_r`.
-      If not specified it defaults to the value returned by selabel_lookup for
+      If not specified, it defaults to the value returned by selabel_lookup for
       the file, if any exists.  Only valid on systems with SELinux support
       enabled."
 
@@ -121,7 +121,7 @@ def sync
   Puppet::Type.type(:file).newproperty(:seltype, :parent => Puppet::SELFileContext) do
     desc "What the SELinux type component of the context of the file should be.
       Any valid SELinux type component is accepted.  For example `tmp_t`.
-      If not specified it defaults to the value returned by selabel_lookup for
+      If not specified, it defaults to the value returned by selabel_lookup for
       the file, if any exists.  Only valid on systems with SELinux support
       enabled."
 
@@ -132,7 +132,7 @@ def sync
   Puppet::Type.type(:file).newproperty(:selrange, :parent => Puppet::SELFileContext) do
     desc "What the SELinux range component of the context of the file should be.
       Any valid SELinux range component is accepted.  For example `s0` or
-      `SystemHigh`.  If not specified it defaults to the value returned by
+      `SystemHigh`.  If not specified, it defaults to the value returned by
       selabel_lookup for the file, if any exists.  Only valid on systems with
       SELinux support enabled and that have support for MCS (Multi-Category
       Security)."

lib/puppet/type/package.rb

@@ -301,12 +301,13 @@ def self.parameters_to_include
             command  => '/opt/ruby/bin/gem',
           }
 
-        Each provider defines a package management command; and uses the first
+        Each provider defines a package management command and uses the first
         instance of the command found in the PATH.
 
         Providers supporting the targetable feature allow you to specify the
-        absolute path of the package management command; useful when multiple
-        instances of the command are installed, or the command is not in the PATH.
+        absolute path of the package management command. Specifying the absolute
+        path is useful when multiple instances of the command are installed, or
+        the command is not in the PATH.
       EOT
 
       isnamevar

lib/puppet/type/user.rb

@@ -231,7 +231,7 @@ def change_to_s(currentvalue, newvalue)
         * OS X 10.8 and higher use salted SHA512 PBKDF2 hashes. When managing passwords
           on these systems, the `salt` and `iterations` attributes need to be specified as
           well as the password.
-        * macOS 10.15 and higher require the salt to be 32-bytes. Since Puppet's user
+        * macOS 10.15 and later require the salt to be 32 bytes. Because Puppet's user
           resource requires the value to be hex encoded, the length of the salt's
           string must be 64.
         * Windows passwords can be managed only in cleartext, because there is no Windows