docs: Update some of the lexical section.
Add a bit more details on dollar-quoting.
Describe `;` as a statement separator.
Add details on comments.
Move the "Operators" section and make "Operator Precedence" a
sub-section.
@@ -205,6 +205,20 @@ all the symbols between the quotes exactly as typed.
... world';
{'hello \nworld'}
+.. _ref_eql_lexical_dollar_quoting:
+
+Dollar-quoted String Constants
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A special case of raw strings are *dollar-quoted* strings. They allow
+using either kind of quote symbols ``'`` or ``"`` as part of the
+string content without the quotes terminating the string. In fact,
+because the *dollar-quote* delimiter sequences can have arbitrary
+alphanumeric additional fillers, it is always possible to surround any
+content with *dollar-quotes* in an unambiguous manner:
+
+.. code-block:: edgeql-repl
+
db> SELECT $$hello
... world$$;
{'hello \nworld'}
@@ -212,6 +226,9 @@ all the symbols between the quotes exactly as typed.
db> SELECT $$hello\nworld$$;
{'hello\\nworld'}
+ db> SELECT $$"hello" 'world'$$;
+ {'"hello" \'world\''}
+
db> SELECT $a$hello$$world$$$a$;
{'hello$$world$$'}
@@ -254,33 +271,32 @@ Here's a list of valid :token:`bytes_escapes`:
+--------------------+---------------------------------------------+
-
-.. _ref_eql_lexical_dollar_quoting:
-
-Dollar-quoted String Constants
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-
-Operators
----------
-
-.. TODO
-
-
Punctuation
-----------
-.. TODO
+EdgeQL uses ``;`` as a statement separator. It is idempotent, so
+multiple repetitions of ``;`` don't have any additional effect.
Comments
--------
+Comments start with a ``#`` character that is not otherwise part of a
+string literal and end at the end of line. Semantically, a comment is
+equivalent to whitespace.
+
+.. productionlist:: edgeql
+ comment: "#" <any other characters until the end of line>
+
+
+Operators
+---------
+
.. TODO
Operator Precedence
--------------------
+^^^^^^^^^^^^^^^^^^^
EdgeQL operators listed in order of precedence from lowest to highest:
