Re: psql's commit df9f599b is not documented

Greetings,

* Tom Lane (tgl(at)sss(dot)pgh(dot)pa(dot)us) wrote:
> Dave Cramer <davecramer(at)postgres(dot)rocks> writes:
> > I would agree. If it's worth coding it's worth documenting. Unless of
> > course the intention is that this is temporary.
>
> Documenting it would mean committing to keeping it indefinitely,
> which I think was exactly what people didn't want to do. It's
> a kluge and we might find ourselves backed into a situation where
> we have to take it out.

Given that it's been a while since 11 came out, this argument doesn't
seem like it really holds much water.

> > Do we have other undocumented features ?
>
> Yup. There are plenty of behaviors that are explained in code comments
> but not anywhere user-visible. If we tried to document absolutely
> everything that someone might be curious about, the manual would be
> three times its current size, but not more useful.

This isn't a deep internal behavior that we're talking about, it's a
very user-visible feature and now we're having users discover it and
then complain that it's not documented. I tend to agree with the
original poster and some others on this thread that it probably should
be documented.

Across major versions, if we feel the need to for whatever reason, we
can take it out even when it's documented. We've certainly done so for
other things in the past, I don't see why this should be viewed as
special in that regard.

Thanks,

Stephen