raminqaf commented on code in PR #29864:
URL: https://github.com/apache/flink/pull/29864#discussion_r4601034401
##########
docs/README.md:
##########
@@ -283,3 +285,49 @@ Renders a link to a file in the Apache Flink Python
Documentation.
```
Renders a link to the apache flink download page.
+
+## Built-in function pages
+
+Pages for built-in SQL functions live under
`content/docs/sql/built-in-functions/<category>/`. They aren't written in
Markdown. A content adapter generates each page, in English and Chinese, from
one YAML file in `data/functions/`.
+
+### Adding a function
+
+1. Add `data/functions/<category>/<name>.yml`. `<category>` is the directory
of the category under `content/docs/sql/built-in-functions/`, such as
`regular-expressions`. `<name>` is the function name in lower case, such as
`regexp_extract`, and the page is served at `<category>/regexp-extract/`. Use
`data/functions/regular-expressions/regexp_extract.yml` as the reference for
the fields.
+2. Add a row for the function to its category in `data/sql_functions.yml` and
`data/sql_functions_zh.yml`. Keep the rows in alphabetical order of the
function name, the order of the pages in the sidebar. Give it `sql`, `table`
and `page: regexp-extract`, without a `description`. The table shows the
function's name, links it to the page and shows the page's summary.
+3. Build the docs as described above and check the page in both languages. A
broken `ref` fails the build, locally and in CI.
+
+The Chinese page renders the same YAML, so the English text is its placeholder
until someone translates it. If you aren't a native Chinese speaker, don't
translate: add no Chinese file and leave the translation to native speakers. A
translation goes in `data/functions_zh/<category>/<name>.yml`, and the fields
it sets replace the English ones.
+
+### What goes on a page
+
+Every page has the same sections, in this order. A section is left out when
the YAML has no field for it.
+
+| Section | What it says
|
+|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Summary | One sentence on what the function returns. The category table
shows it too.
|
+| See also | Related functions, listed under the summary.
|
+| Syntax | The SQL call, and the Java and Python Table API calls where
they exist. There is no Scala tab, since the Scala API is deprecated.
|
+| Arguments | For each argument: the accepted types in plain words, whether
it is required, its default and what it means.
|
+| Returns | What the function returns, then the cases that return NULL,
then the return type and whether it is nullable.
|
+| Usage notes | What a user of the function needs and can't tell from the
sections above, such as limits and determinism.
|
+| Examples | A list of the scenarios, then each scenario with a title, one
sentence, the SQL and its result. A Table API-only function shows Java and
Python code instead. |
+
+NULL handling has no section of its own. It goes into Returns, and the
examples show it.
+
+### What to leave out
+
+A page tells a user how to use the function, not everything the code does.
Leave out:
+
+- Behavior that all functions share, such as that an untyped `NULL` needs a
cast, or that arguments of the wrong type fail at planning time.
+- Internal behavior, such as how the planner rewrites a call or how its code
is generated.
+- Exact error messages. Say when a call fails instead, such as "Not supported
in streaming mode."
+- Types and inputs that few users would try. Name the accepted types in plain
words, as other engines do, such as "Any comparable type".
+- Common sense, such as that a call needs its parentheses.
+- Bugs. A page describes the intended behavior, and a bug goes to Jira.
Review Comment:
Agreed. The pages now describe the current behavior, without ticket numbers.
For example, LAG and LEAD say that with a NOT NULL `default`, a NULL value
comes back as a placeholder such as `-1`, or the job fails, depending on the
query. The README guide says to file the bug with the intended behavior and to
update the page in the PR that fixes it.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]