Marginal comments and docs cleanup.

Fix up some imprecise comments and poor markup from ba79cb5dc.  Also try
to convert the documentation of log_min_duration_sample and friends into
passable English.

doc/src/sgml/config.sgml

@@ -5984,13 +5984,13 @@ local0.*    /var/log/postgresql
         <para>
          Causes the duration of each completed statement to be logged
          if the statement ran for at least the specified amount of time.
-         If this value is specified without units, it is taken as milliseconds.
-         Setting this to zero prints all statement durations.
-         Minus-one (the default) disables logging statement durations.
          For example, if you set it to <literal>250ms</literal>
          then all SQL statements that run 250ms or longer will be
          logged.  Enabling this parameter can be helpful in tracking down
          unoptimized queries in your applications.
+         If this value is specified without units, it is taken as milliseconds.
+         Setting this to zero prints all statement durations.
+         Minus-one (the default) disables logging statement durations.
          Only superusers can change this setting.
         </para>
 
@@ -6030,49 +6030,39 @@ local0.*    /var/log/postgresql
       </term>
        <listitem>
         <para>
-         Allows to sample the logging of the duration of each completed
+         Allows sampling the duration of completed statements that ran for
-         statement if the statement ran for at least the specified amount of
+         at least the specified amount of time.  This produces the same
-         time. If this value is specified without units, it is taken as milliseconds.
+         kind of log entries as
+         <xref linkend="guc-log-min-duration-statement"/>, but only for a
+         subset of the executed statements, with sample rate controlled by
+         <xref linkend="guc-log-statement-sample-rate"/>.
+         For example, if you set it to <literal>100ms</literal> then all
+         SQL statements that run 100ms or longer will be considered for
+         sampling.  Enabling this parameter can be helpful when the
+         traffic is too high to log all queries.
+         If this value is specified without units, it is taken as milliseconds.
          Setting this to zero samples all statement durations.
          Minus-one (the default) disables sampling statement durations.
-         For example, if you set it to <literal>250ms</literal>
-         then all SQL statements that run 250ms or longer will be considered
-         for sampling, with sample rate is controlled by <xref linkend="guc-log-statement-sample-rate"/>. 
-         Enabling this parameter can be helpful when the traffic too high to
-         sample all queries.
          Only superusers can change this setting.
         </para>
 
         <para>
-         This option has lower priority than <xref linkend="guc-log-min-duration-statement"/>,
+         This setting has lower priority
-         meaning that statements with durations exceeding <xref linkend="guc-log-min-duration-statement"/>
+         than <varname>log_min_duration_statement</varname>, meaning that
-         are not subject to sampling and are always logged.
+         statements with durations
+         exceeding <varname>log_min_duration_statement</varname> are not
+         subject to sampling and are always logged.
         </para>
 
         <para>
-         For clients using extended query protocol, durations of the Parse,
+         Other notes for <varname>log_min_duration_statement</varname>
-         Bind, and Execute steps are logged independently.
+         apply also to this setting.
         </para>
-
-       <note>
-        <para>
-         When using this option together with
-         <xref linkend="guc-log-statement"/>,
-         the text of statements that are logged because of
-         <varname>log_statement</varname> will not be repeated in the
-         duration log message.
-         If you are not using <application>syslog</application>, it is recommended
-         that you log the PID or session ID using
-         <xref linkend="guc-log-line-prefix"/>
-         so that you can link the statement message to the later
-         duration message using the process ID or session ID.
-        </para>
-       </note>
        </listitem>
      </varlistentry>
 
      <varlistentry id="guc-log-statement-sample-rate" xreflabel="log_statement_sample_rate">
-      <term><varname>log_statement_sample_rate</varname> (<type>real</type>)
+      <term><varname>log_statement_sample_rate</varname> (<type>floating point</type>)
       <indexterm>
        <primary><varname>log_statement_sample_rate</varname> configuration parameter</primary>
       </indexterm>
@@ -6080,43 +6070,40 @@ local0.*    /var/log/postgresql
        <listitem>
         <para>
          Determines the fraction of statements with duration exceeding
-         <xref linkend="guc-log-min-duration-sample"/> to be logged.
+         <xref linkend="guc-log-min-duration-sample"/> that will be logged.
-         This is a statistical parameter, for example <literal>0.5</literal>
+         Sampling is stochastic, for example <literal>0.5</literal> means
-         means there is statistically one in two chances to log the statement.
+         there is statistically one chance in two that any given statement
-         The default is <literal>1.0</literal>, meaning log all such
+         will be logged.
+         The default is <literal>1.0</literal>, meaning to log all sampled
          statements.
-         Setting this to zero disables sampling logging, same as setting
+         Setting this to zero disables sampled statement-duration logging,
+         the same as setting
          <varname>log_min_duration_sample</varname> to
          <literal>-1</literal>.
-         <varname>log_statement_sample_rate</varname> is helpful when the
-         traffic is too high to log all queries.
          Only superusers can change this setting.
         </para>
-       <note>
-        <para>
-         Like all statement-logging options, this option can add significant
-         overhead.
-        </para>
-       </note>
        </listitem>
      </varlistentry>
 
      <varlistentry id="guc-log-transaction-sample-rate" xreflabel="log_transaction_sample_rate">
-      <term><varname>log_transaction_sample_rate</varname> (<type>real</type>)
+      <term><varname>log_transaction_sample_rate</varname> (<type>floating point</type>)
       <indexterm>
        <primary><varname>log_transaction_sample_rate</varname> configuration parameter</primary>
       </indexterm>
       </term>
        <listitem>
         <para>
-         Set the fraction of transactions whose statements are all logged,
+         Sets the fraction of transactions whose statements are all logged,
          in addition to statements logged for other reasons.  It applies to
          each new transaction regardless of its statements' durations.
-         The default is <literal>0</literal>, meaning not to log statements
+         Sampling is stochastic, for example <literal>0.1</literal> means
-         from any additional transaction.  Setting this to <literal>1</literal>
+         there is statistically one chance in ten that any given transaction
-         logs all statements for all transactions.
+         will be logged.
-         <varname>log_transaction_sample_rate</varname> is helpful to track a
+         <varname>log_transaction_sample_rate</varname> can be helpful to
-         sample of transaction.
+         construct a sample of transactions.
+         The default is <literal>0</literal>, meaning not to log
+         statements from any additional transactions.  Setting this
+         to <literal>1</literal> logs all statements of all transactions.
          Only superusers can change this setting.
         </para>
        <note>
@@ -6632,9 +6619,9 @@ log_line_prefix = '%m [%p] %q%u@%d/%a '
        <para>
         Controls whether bind parameters are logged when a statement is logged
         as a result of <xref linkend="guc-log-min-error-statement"/>.
-        It adds some overhead, as postgres will compute and store textual
+        It adds some overhead, as <productname>PostgreSQL</productname> will
-        representations of parameter values in memory for all statements,
+        compute and store textual representations of parameter values in
-        even if they eventually do not get logged.
+        memory for all statements, even if they eventually do not get logged.
         This setting has no effect on statements logged due to
         <xref linkend="guc-log-min-duration-statement"/> or
         <xref linkend="guc-log-statement"/> settings, as they are always logged

src/backend/nodes/params.c

@@ -262,16 +262,16 @@ RestoreParamList(char **start_address)
 
 /*
  * BuildParamLogString
- *		Return a string that represent the parameter list, for logging.
+ *		Return a string that represents the parameter list, for logging.
  *
  * If caller already knows textual representations for some parameters, it can
  * pass an array of exactly params->numParams values as knownTextValues, which
  * can contain NULLs for any unknown individual values.  NULL can be given if
  * no parameters are known.
  *
- * If maxlen is not zero, that's the maximum number of characters of the
+ * If maxlen is not zero, that's the maximum number of bytes of any one
- * input string printed; an ellipsis is added if more characters exist.
+ * parameter value to be printed; an ellipsis is added if the string is
- * (Added quotes are not considered.)
+ * longer.  (Added quotes are not considered in this calculation.)
  */
 char *
 BuildParamLogString(ParamListInfo params, char **knownTextValues, int maxlen)
@@ -282,7 +282,8 @@ BuildParamLogString(ParamListInfo params, char **knownTextValues, int maxlen)
 
 	/*
 	 * NB: think not of returning params->paramValuesStr!  It may have been
-	 * generated with a different maxlen, and so unsuitable.
+	 * generated with a different maxlen, and so be unsuitable.  Besides that,
+	 * this is the function used to create that string.
 	 */
 
 	/*

src/backend/utils/mb/stringinfo_mb.c

@@ -26,7 +26,7 @@
 /*
  * appendStringInfoStringQuoted
  *
- * Append up to maxlen characters from s to str, or the whole input string if
+ * Append up to maxlen bytes from s to str, or the whole input string if
  * maxlen <= 0, adding single quotes around it and doubling all single quotes.
  * Add an ellipsis if the copy is incomplete.
  */