Re: doc: Clarify ANALYZE VERBOSE output

On Mon, Apr 13, 2026 at 3:29 PM David G. Johnston
<david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>> On Tue, Apr 7, 2026 at 6:57 PM Shinya Kato <shinya11(dot)kato(at)gmail(dot)com> wrote:
>> > I believe the current "Outputs" section is intentionally kept simple to minimize maintenance overhead. While expanding it might be a worthwhile follow-up, it probably deserves its own dedicated discussion.
>>
>> +1, listing output details is signing up for busywork.
>
>
> Given how expansive and thorough our documentation is, and the fact this is user-facing output, I'm not seeing why this gets a pass on the documentation requirement. That said, I concur this patch needn't be responsible for dealing with that - I'm not even sure whether trying to do that on the vacuum/analyze pages is even the correct choice since at least some of what is output is object-specific and not generic to vacuum itself. Though stuff like timings are. Even if we want to leave ourselves the "it's undocumented so it can be changed at will" clause we can simply write that in.

It's not getting "a pass". Ultimately it's a judgment call:
maintenance cost versus existing conventions (how we document command
output in other places), utility to the user of having detailed docs
on this, and how easy it is to check the actual output by just running
the command. I think on balance it's not worth doing here, and "it's
undocumented so it can be changed at will" is equivalent to saying
nothing (so we might as well say nothing).

>> maybe something
>> along these lines:
>>
>> "Prints detailed stats at <literal>INFO</literal> level for each table
>> as it is processed."
>>
>
> I really don't like the word "Print" here. What the client decides to do with the INFO message is up to them - the interface to document for the server is simply sending the message and its details.

Fair enough, though we do use "print" as a synonym for "log" all over
the place. "Emit" was suggested down-thread; I think that's also a
good choice. Your "Sends" below also works.

> I was apparently mistaken about this info showing in the server log file though.
>
> So that leaves me with suggesting:
>
> "Enables the sending of a detailed INFO message to the client after each table is processed."

I'd simplify it to just

"Sends a detailed INFO message to the client after each table is processed."

Technically the option itself is not doing the sending, but the
relationship of the option to the behavior is obvious, and I don't
think complicating the language to reflect the actual mechanism adds
anything.

Thanks,
Maciek