Merging upstream version 20.3.0.

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

1 files changed, 12 insertions, 8 deletions

diff --git a/sqlglot/dialects/__init__.py b/sqlglot/dialects/__init__.py
index 8212669..04990ac 100644
--- a/sqlglot/dialects/__init__.py
+++ b/sqlglot/dialects/__init__.py
@@ -12,7 +12,7 @@ classes as needed.
 
 ### Implementing a custom Dialect
 
-Consider the following example:
+Creating a new SQL dialect may seem complicated at first, but it is actually quite simple in SQLGlot:
 
 ```python
 from sqlglot import exp
@@ -23,9 +23,10 @@ from sqlglot.tokens import Tokenizer, TokenType
 
 class Custom(Dialect):
     class Tokenizer(Tokenizer):
-        QUOTES = ["'", '"']
-        IDENTIFIERS = ["`"]
+        QUOTES = ["'", '"']  # Strings can be delimited by either single or double quotes
+        IDENTIFIERS = ["`"]  # Identifiers can be delimited by backticks
 
+        # Associates certain meaningful words with tokens that capture their intent
         KEYWORDS = {
             **Tokenizer.KEYWORDS,
             "INT64": TokenType.BIGINT,
@@ -33,8 +34,12 @@ class Custom(Dialect):
         }
 
     class Generator(Generator):
-        TRANSFORMS = {exp.Array: lambda self, e: f"[{self.expressions(e)}]"}
+        # Specifies how AST nodes, i.e. subclasses of exp.Expression, should be converted into SQL
+        TRANSFORMS = {
+            exp.Array: lambda self, e: f"[{self.expressions(e)}]",
+        }
 
+        # Specifies how AST nodes representing data types should be converted into SQL
         TYPE_MAPPING = {
             exp.DataType.Type.TINYINT: "INT64",
             exp.DataType.Type.SMALLINT: "INT64",
@@ -48,10 +53,9 @@ class Custom(Dialect):
         }
 ```
 
-This is a typical example of adding a new dialect implementation in SQLGlot: we specify its identifier and string
-delimiters, as well as what tokens it uses for its types and how they're associated with SQLGlot types. Since
-the `Expression` classes are common for each dialect supported in SQLGlot, we may also need to override the generation
-logic for some expressions; this is usually done by adding new entries to the `TRANSFORMS` mapping.
+The above example demonstrates how certain parts of the base `Dialect` class can be overridden to match a different
+specification. Even though it is a fairly realistic starting point, we strongly encourage the reader to study existing
+dialect implementations in order to understand how their various components can be modified, depending on the use-case.
 
 ----
 """