Go into more detail about handling the parens in parse_table_factor

Author: nickolay

src/sqlparser.rs

@@ -1694,21 +1694,34 @@ impl Parser {
             // time which it is... so we just try to parse both.
             //
             // Here's an example that demonstrates the complexity:
-            //
-            //     SELECT * FROM ( ( (SELECT 1) UNION (SELECT 2) ) AS t1 NATURAL JOIN t2 )
-            //                   ^ ^ ^
-            //                   | | |
-            //                   | | belongs to the subquery
-            //                   | starts a derived table (subquery)
-            //                   starts a nested join
+            //                     /-------------------------------------------------------\
+            //                     | /-----------------------------------\                 |
+            //     SELECT * FROM ( ( ( (SELECT 1) UNION (SELECT 2) ) AS t1 NATURAL JOIN t2 ) )
+            //                   ^ ^ ^ ^
+            //                   | | | |
+            //                   | | | |
+            //                   | | | (4) belongs to a SQLSetExpr::Query inside the subquery
+            //                   | | (3) starts a derived table (subquery)
+            //                   | (2) starts a nested join
+            //                   (1) an additional set of parens around a nested join
             //
             match self.parse_derived_table_factor(NotLateral) {
+                // The recently consumed '(' started a derived table, and we've
+                // parsed the subquery, followed by the closing ')', and the
+                // alias of the derived table. In the example above this is
+                // case (3), and the next token would be `NATURAL`.
                 Ok(table_factor) => Ok(table_factor),
                 Err(_) => {
-                    // It wasn't a derived table. Ignore the error and back up
-                    // to where we were before. Either we'll be able to parse a
-                    // valid nested join, or we won't, and we'll return that
-                    // error instead.
+                    // The '(' we've recently consumed does not start a derived
+                    // table. For valid input this can happen either when the
+                    // token following the paren can't start a query (e.g. `foo`
+                    // in `FROM (foo NATURAL JOIN bar)`, or when the '(' we've
+                    // consumed is followed by another '(' that starts a
+                    // derived table, like (3), or another nested join (2).
+                    //
+                    // Ignore the error and back up to where we were before.
+                    // Either we'll be able to parse a valid nested join, or
+                    // we won't, and we'll return that error instead.
                     self.index = index;
                     let table_and_joins = self.parse_table_and_joins()?;
                     match table_and_joins.relation {