Hi,
On 04/09/2016 01:21 AM, Tatsuo Ishii wrote:
> From: Tomas Vondra <tomas.vondra@2ndquadrant.com>
...
> My feedback regarding docs were:
>> - There's no docs for pg_mv_statistic (should be added to "49. System
>> Catalogs")
>>
>> - The word "multivariate statistics" or something like that should
>> appear in the index.
>>
>> - There are some explanation how to deal with multivariate statistics
>> in "14.1 Using Explain" and "14.2 Statistics used by the Planner"
>> section.
>
> The second and the third point maybe are something like "polishing
> user-level" docs, but I don't think the first one is for "user-level".
> Also I think without the first one the patch will be never
> committable. If someone add a new system catalog, the doc should be
> added to "System Catalogs" section, that's our standard, at least in
> my understanding.
I do apologize if it seemed that I don't value your review, and I do
agree that those changes need to be done, although I still see them
rather as a user-level docs (as opposed to READMEs/comments, which I
think are used by developers much more often).
But I still think it wouldn't move the patch any closer to committable
state, because what it really needs is review whether the catalog
definition makes sense, whether it should be more like pg_statistic, and
so on. Only then it makes sense to describe the catalog structure in the
SGML docs, I think. That's why I added some basic SGML docs for
CREATE/DROP/ALTER STATISTICS, which I expect to be rather stable, and
not the catalog and other low-level stuff (which is commented heavily in
the code anyway).
Had the patch been a Titanic, fixing the SGML docs a few days before the
code freeze would be akin to washing the deck instead of looking for
icebergs on April 15, 1912.
regards
--
Tomas Vondra http://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
