On Sat, Mar 26, 2022 at 6:25 PM James Coleman <jtc...@gmail.com> wrote: > I simply do not accept the claim that this is not a reasonable concern > to have nor that this isn't worth documenting.
I don't think I said that the concern wasn't reasonable, but I don't think the fact that one person or organization had a concern means that it has to be worth documenting. And I didn't say either that it's not intrinsically worth documenting. I said it doesn't fit nicely into the documentation we have. Since you didn't like my last example, let's try another one. If someone shows up and proposes a documentation patch to explain what a BitmapOr node means, we're probably going to reject it, because it makes no sense to document that one node and not all the others. That doesn't mean that people shouldn't want to know what BitmapOr means, but it's just not sensible to document that one thing in isolation, even if somebody somewhere happened to be confused by that thing and not any of the other nodes. In the same way, I think you're trying to jam documentation of one particular point into the documentation when there are many other similar points that are not documented, and I think it's very awkward. It looks to me like you want to document that a table scan isn't performed in a certain case when we haven't documented the rule that would cause that table scan to be performed in other cases, or even what a table scan means in this context, or any of the similar things that are equally important, like a table rewrite or an index rebuild, or any of the rules for when those things happen. It's arguable in my mind whether it is worth documenting all of those rules, although I am not opposed to it if somebody wants to do the work. But I *am* opposed to documenting that a certain situation is an exception to an undocumented rule about an undocumented concept. That's going to create confusion, not dispel it. -- Robert Haas EDB: http://www.enterprisedb.com
