Merge pull request puppetlabs#9422 from joshcooper/doc_updates

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

Author: cthorn42

lib/puppet/application/apply.rb

@@ -153,6 +153,7 @@ def help
 
       EXAMPLE
       -------
+          $ puppet apply -e 'notify { "hello world": }'
           $ puppet apply -l /tmp/manifest.log manifest.pp
           $ puppet apply --modulepath=/root/dev/modules -e "include ntpd::server"
           $ puppet apply --catalog catalog.json

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

@@ -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,8 +162,8 @@ 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 => "Specifies whether to suppress the notice of which compiler
+        supplied the catalog. A value of `true` suppresses the notice.",
     },
     :merge_dependency_warnings => {
       :default => false,
@@ -417,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 => {
@@ -1204,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
@@ -1240,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,
@@ -1492,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",
@@ -1745,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",
@@ -1775,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']`."
     },
@@ -2091,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/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/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/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")'
 # ```
 #

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/ctime.rb

@@ -2,9 +2,9 @@
 
 module Puppet
   Puppet::Type.type(:file).newproperty(:ctime) do
-    desc %q(A read-only state to check the file ctime. On most modern \*nix-like
+    desc "A read-only state to check the file ctime. On most modern \*nix-like
       systems, this is the time of the most recent change to the owner, group,
-      permissions, or content of the file.)
+      permissions, or content of the file."
 
     def retrieve
       current_value = :absent

lib/puppet/type/file/mtime.rb

@@ -2,8 +2,8 @@
 
 module Puppet
   Puppet::Type.type(:file).newproperty(:mtime) do
-    desc %q(A read-only state to check the file mtime. On \*nix-like systems, this
-      is the time of the most recent change to the content of the file.)
+    desc "A read-only state to check the file mtime. On \*nix-like systems, this
+      is the time of the most recent change to the content of the file."
 
     def retrieve
       current_value = :absent