Merging upstream version 10.0.1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 35 insertions, 14 deletions

diff --git a/README.md b/README.md
index 0d7e429..b00b803 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ Contributions are very welcome in SQLGlot; read the [contribution guide](https:/
 
 * [Install](#install)
 * [Documentation](#documentation)
-* [Run Tests & Lint](#run-tests-and-lint)
+* [Run Tests and Lint](#run-tests-and-lint)
 * [Examples](#examples)
    * [Formatting and Transpiling](#formatting-and-transpiling)
    * [Metadata](#metadata)
@@ -22,7 +22,6 @@ Contributions are very welcome in SQLGlot; read the [contribution guide](https:/
    * [Unsupported Errors](#unsupported-errors)
    * [Build and Modify SQL](#build-and-modify-sql)
    * [SQL Optimizer](#sql-optimizer)
-   * [SQL Annotations](#sql-annotations)
    * [AST Introspection](#ast-introspection)
    * [AST Diff](#ast-diff)
    * [Custom Dialects](#custom-dialects)
@@ -51,7 +50,7 @@ pip3 install -r dev-requirements.txt
 
 ## Documentation
 
-SQLGlot's uses [pdocs](https://pdoc.dev/) to serve its API documentation:
+SQLGlot uses [pdocs](https://pdoc.dev/) to serve its API documentation:
 
 ```
 pdoc sqlglot --docformat google
@@ -121,6 +120,39 @@ LEFT JOIN `baz`
   ON `f`.`a` = `baz`.`a`
 ```
 
+Comments are also preserved in a best-effort basis when transpiling SQL code:
+
+```python
+sql = """
+/* multi
+   line
+   comment
+*/
+SELECT
+  tbl.cola /* comment 1 */ + tbl.colb /* comment 2 */,
+  CAST(x AS INT), # comment 3
+  y               -- comment 4
+FROM
+  bar /* comment 5 */,
+  tbl #          comment 6
+"""
+
+print(sqlglot.transpile(sql, read='mysql', pretty=True)[0])
+```
+
+```sql
+/* multi
+   line
+   comment
+*/
+SELECT
+  tbl.cola /* comment 1 */ + tbl.colb /* comment 2 */,
+  CAST(x AS INT), -- comment 3
+  y -- comment 4
+FROM bar /* comment 5 */, tbl /*          comment 6*/
+```
+
+
 ### Metadata
 
 You can explore SQL with expression helpers to do things like find columns and tables:
@@ -249,17 +281,6 @@ WHERE
   "x"."Z" = CAST('2021-02-01' AS DATE)
 ```
 
-### SQL Annotations
-
-SQLGlot supports annotations in the sql expression. This is an experimental feature that is not part of any of the SQL standards but it can be useful when needing to annotate what a selected field is supposed to be. Below is an example:
-
-```sql
-SELECT
-  user # primary_key,
-  country
-FROM users
-```
-
 ### AST Introspection
 
 You can see the AST version of the sql by calling `repr`: