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]

Reply via email to