Hello,
On 04/09/2016 07:37 PM, Tatsuo Ishii wrote:
>> 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).
>
> Without "user-level docs" (now I understand that the term means all
> SGML docs for you), it is very hard to find a visible
> characteristics/behavior of the patch. CREATE/DROP/ALTER STATISTICS
> just defines a user interface, and does not help how it affects to
> the planning. The READMEs do not help either.
>
> In this case reviewing your code is something like reviewing a
> program which has no specification.
I certainly agree that reviewing a patch without the context is hard. My
intent was to provide such context / explanation in the READMEs, but
perhaps I failed to do so with enough detail.
BTW when you say that READMEs do not help either, does that mean you
consider READMEs unsuitable for this type of information in general, or
that the current READMEs lack important information?
>
> That's the reason why I said before below, but it was never
> seriously considered.>
I've considered it, but my plan was to have detailed READMEs, and then
eventually distill that into something suitable for the SGML (perhaps
without discussion of some implementation details). Maybe that's not the
right approach.
FWIW providing the context is why I started working on a "paper"
explaining both the motivation and implementation, including a bit of
math and figures (which is what we don't have in READMEs or SGML). I
haven't updated it recently, and it probably got buried in the thread,
but perhaps this would be a better way to provide the context?
regards
--
Tomas Vondra http://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
