Subject: Fix bug in VACUUM and ANALYZE docs

From: Ryoga Yoshida <[email-masked]>
Date: Tue, 19 Sep 2023 17:59:11 +0900

Hi,

Issue1:
VACUUM and ANALYZE docs explain that the parameter of BUFFER_USAGE_LIMIT 
is optional as follows. But this is not true. The argument, size, is 
required for BUFFER_USAGE_LIMIT. So the docs should be fixed this issue.
BUFFER_USAGE_LIMIT [ size ]
https://www.postgresql.org/docs/devel/sql-vacuum.html
https://www.postgresql.org/docs/devel/sql-analyze.html

Issue2:
Sizes may also be specified as a string containing the numerical size 
followed by any one of the following memory units: kB (kilobytes), MB 
(megabytes), GB (gigabytes), or TB (terabytes).
VACUUM and ANALYZE docs explain that the argument of BUFFER_USAGE_LIMIT 
accepts the units like kB (kilobytes), MB (megabytes), GB (gigabytes), 
or TB (terabytes). But it also actually accepts B(bytes) as an unit. So 
the docs should include "B(bytes)" as an unit that the argument of 
BUFFER_USAGE_LIMIT can accept.

You can see the patch in the attached file.

Ryoga Yoshida

diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 1fba089265..bc973bdd1e 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -27,7 +27,7 @@ ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <r
 
     VERBOSE [ <replaceable class="parameter">boolean</replaceable> ]
     SKIP_LOCKED [ <replaceable class="parameter">boolean</replaceable> ]
-    BUFFER_USAGE_LIMIT [ <replaceable class="parameter">size</replaceable> ]
+    BUFFER_USAGE_LIMIT <replaceable class="parameter">size</replaceable>
 
 <phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
 
@@ -128,7 +128,7 @@ ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <r
      <para>
       Specifies an amount of memory in kilobytes.  Sizes may also be specified
       as a string containing the numerical size followed by any one of the
-      following memory units: <literal>kB</literal> (kilobytes),
+      following memory units: <literal>B</literal> (bytes), <literal>kB</literal> (kilobytes),
       <literal>MB</literal> (megabytes), <literal>GB</literal> (gigabytes), or
       <literal>TB</literal> (terabytes).
      </para>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 90cde70c07..f2e7c0bbde 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -38,7 +38,7 @@ VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <re
     PARALLEL <replaceable class="parameter">integer</replaceable>
     SKIP_DATABASE_STATS [ <replaceable class="parameter">boolean</replaceable> ]
     ONLY_DATABASE_STATS [ <replaceable class="parameter">boolean</replaceable> ]
-    BUFFER_USAGE_LIMIT [ <replaceable class="parameter">size</replaceable> ]
+    BUFFER_USAGE_LIMIT <replaceable class="parameter">size</replaceable>
 
 <phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
 
@@ -389,7 +389,7 @@ VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <re
      <para>
       Specifies an amount of memory in kilobytes.  Sizes may also be specified
       as a string containing the numerical size followed by any one of the
-      following memory units: <literal>kB</literal> (kilobytes),
+      following memory units: <literal>B</literal> (bytes), <literal>kB</literal> (kilobytes),
       <literal>MB</literal> (megabytes), <literal>GB</literal> (gigabytes), or
       <literal>TB</literal> (terabytes).
      </para>

---

From: Shinya Kato <[email-masked]>
Date: Wed, 20 Sep 2023 09:43:15 +0900

On 2023-09-19 17:59, Ryoga Yoshida wrote:
> Hi,
> 
> Issue1:
> VACUUM and ANALYZE docs explain that the parameter of
> BUFFER_USAGE_LIMIT is optional as follows. But this is not true. The
> argument, size, is required for BUFFER_USAGE_LIMIT. So the docs should
> be fixed this issue.
> VACUUM and ANALYZE docs explain that the argument of
> BUFFER_USAGE_LIMIT accepts the units like kB (kilobytes), MB
> (megabytes), GB (gigabytes), or TB (terabytes). But it also actually
> accepts B(bytes) as an unit. So the docs should include "B(bytes)" as
> an unit that the argument of BUFFER_USAGE_LIMIT can accept.
> 

Thanks for the patch.
You're right. It looks good to me.

-- 
Regards,
Shinya Kato
NTT DATA GROUP CORPORATION