On Fri, Jun 3, 2016 at 11:25 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Michael Paquier <michael.paquier@gmail.com> writes: >> Actually, the docs could be more polished. > > I think the docs could stand to be rewritten from scratch ;-). But > upthread there was an offer to work on them if we made the code behavior > saner. I've done the latter part, I don't want to do the former.
I have finally given a shot at improving the docs with the attached. Comments are welcome.
Looks good. Thanks!
Some minor word-smithing related stuff and one definitional concern:
"of all indexed attributes and so it can report false positives" -> of all indexed attributes and as such is prone to reporting false positives;
"in the set, however" -> "in the set although"
"one only needs a single bloom index (default 80, maximum 4096)" -> the default seems like it would be better placed in the first paragraph of the intro where "whose size in calculated in bits" is mentioned; or better yet dropped altogether since the parameters section covers the defaults.
*** "to the number of the column for" - the examples imply that each parameter refers to columns by name, not number.
"a bloom index representing first the advantage to be more" - this intro to the example needs some work. maybe: "Here is a more complete example of index definition and usage, as well as a comparison with the equivalent btree index. The bloom index is considerably smaller as well as performs better than the btree index.
---As an aside, is a multi-column index really a fair comparison here?
---Leaving a sequential scan explain analyze in place should be considered.
"The Bloom opclass interface" -> The Bloom opclass interface requires a hash function for the indexing datatype and an equality operator for searching. The example...(drop the simple conclusion the word the equality operator part better).
"are implemented with the module" - are supplied by this module. (side question, for 10.0 how about we call these extensions instead of modules?)
