On Wed, Aug 5, 2020 at 5:29 PM Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Aug 4, 2020 at 03:56:32PM +0000, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/12/functions-textsearch.html > Description: > > A suggestion. This page, "functions-textsearch", is fine, and the best > place to explain functions like array_to_tsvector() and jsonb_to_tsvector(). > The suggestion is just to cite these native functions in the Guide's "hub > page" of respective prefixes...
> Simple citation anywhere in the hub page, or a simple "See also" section to > list the non-explained functions that can be also classifyed as valid > function for that hub page.
Uh, I am not sure it helps to mention that there are text search-specific functions in the generic sections.
By that logic array_to_text should exist under string functions and not array functions (I would seriously consider this specific change).
However, the premise that the array and json pages are "hub pages" is not one that I support. They are not lacking information but simply do not attempt to fulfill such a broad mandate. If a user wishs to know every function/operator in their database that accepts an array as input or outputs an array that would be better served by querying the database and not scanning documentation. Nor do I find it plausible that given a function name array_to_tsvector that is difficult to locate - even without using search - if the function is only listed in the text search section.
In short, I see no usability gap here that needs to be fixed. I'll agree that it could be different but I don't believe that it would be an obvious improvement even if an actual patch were presented for discussion.
