Extra documentation would be nice. But who is going to write (and maintain) this extra documentation?
Even the current documentation takes a lot of work. When reviewing a PR to add a function, I have to tell people to remove a ‘.’ at the end of the line to be consistent with the existing doc. Without those efforts, the documentation would be a shambles, and no one would trust it. We have over 500 functions. Julian > On Jan 24, 2024, at 9:46 AM, Mihai Budiu <mbu...@gmail.com> wrote: > > I think we should make a separate document for the functions, and in general > give more details about the functions' behavior. The current model is to give > a very brief description of the function, but that's often not enough, users > have to resort to either experiments or to reading documentation from other > databases. The behavior should be described for corner cases, and ideally > there should be examples as well. > > Mihai > ________________________________ > From: Cancai Cai <can...@apache.org> > Sent: Wednesday, January 24, 2024 7:14 AM > To: dev@calcite.apache.org <dev@calcite.apache.org> > Subject: Refactor reference.md > > Hey Calcite Devs, > > I am currently working on CALCITE-6215 > <https://issues.apache.org/jira/browse/CALCITE-6215>. During my work, I > have noticed that certain functions have multiple variations with different > parameter types in their respective databases. For example, in PostgreSQL, > the to_char function supports multiple forms such as to_char(timestamp, > text), to_char(interval, text), and to_char(numeric_type, text). > > However, the description in Calcite is not clear enough. For instance, the > reference.md document describes the to_char function as follows: > > | m o p | TO_CHAR(timestamp, format) | Converts *timestamp* to a string > using the format *format*. > > This description may not provide enough clarity for users to understand the > usage of each function across different databases. > > I suggest considering adding specific links to the corresponding database > functions in the reference.md document to enhance its completeness. This > would allow users to easily access the documentation for the respective > database functions. > > Thanks as always, > > Cancai Cai > > https://www.postgresql.org/docs/16/functions-formatting.html#FUNCTIONS-FORMATTING-DATETIME-TABLE
