Thread: need for "see also" section or similar thing at hub pages
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... Ideal, for Guide reader, is to be informed about the existence of all array functions in the Array's hub page, https://www.postgresql.org/docs/current/functions-array.html , and all JSON functions in the JSON's hub page https://www.postgresql.org/docs/current/functions-json.html 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.
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... > > Ideal, for Guide reader, is to be informed about the existence of all array > functions in the Array's hub page, > https://www.postgresql.org/docs/current/functions-array.html , and all JSON > functions in the JSON's hub page > https://www.postgresql.org/docs/current/functions-json.html > > 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. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
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.
David J.