The documentation would be incrementally improved, like the codebase. We could start by just moving it to a different file. The narrow table also makes it difficult to read, so perhaps we can reformat that. A third column would be nice for examples, but it would mostly be empty initially. Some functions require additional clarifications as long text, maybe these can be footnotes?
Another solution is to make a separate table for each class of functions: string, numeric, array, etc. That would make it easier to intersperse with additional notes. The terse format makes it very difficult to explain things that are subtle. For example, see my PR https://github.com/apache/calcite/pull/3571 which only attempts to clarify something, but has not been approved since early December. Mihai ________________________________ From: Julian Hyde <[email protected]> Sent: Wednesday, January 24, 2024 12:54 PM To: [email protected] <[email protected]> Subject: Re: Refactor reference.md 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 <[email protected]> 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 <[email protected]> > Sent: Wednesday, January 24, 2024 7:14 AM > To: [email protected] <[email protected]> > 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
