Document Restrictions::STMT_EXPR better

[ehuss]

The Restrictions::STMT_EXPR restriction could be better documented. Currently we have:

• The Expression grammar is split into ExpressionWithoutBlock and ExpressionWithBlock. These are used somewhat to indicate that block-like expressions have different behavior in different places.
• statement.expr.restriction-semicolon tries to explain the ambiguity of how a block expression is not treated as part of another expression in statement positions.

In statement position, if match blocks (except async) while loop for try const stop parsing in certain ways and do not follow things like associative operators. This is used in various places like statement position, but also match arms, etc.

This restriction has many consequences, like in the following examples:

// In statement position, this is two statements.
// Otherwise it is a call on the value of the `if` expression.
if true {}
(1,2,3)

// This fails to parse. `{1}` is a statement (parsing stops at `+` due to STMT_EXPR).
// `+{2}` (or `+2`) is not a valid statement or expression.
{{1}+{2}};

    // These modifications work:
    {1 + {2}};
    {({1}) + {2}};

// Same as above, fails since the `match` is a statement, parsing stops at `+`.
match () { () => 1 } + 2;

// This parses (two statements, a block and an unary `-` expression), then
// fails typecheck because blocks without semicolon need to be unit.
{1}-1;

// This works because STMT_EXPR does *not* stop parsing on `.`.
{"abc"}.len();

Various things to consider:

• Need to double check that the existing parts are covered correctly and completely.
• Document where "statement position" is? Not sure if existing grammar handles this well enough.
• See notes in Document Restrictions::NO_STRUCT_LITERAL better #1808 about how this state is "sticky", and should document where it starts and ends.
  • I don't know how this should be encoded in the grammar. Currently we try with splitting Expression in two, but like Document Restrictions::NO_STRUCT_LITERAL better #1808 this runs into problems since the state is maintained while recursing. Maybe this should use suffixes like that issue instead? I don't really know how that should be approached.

See all the calls to expr_is_complete(), which is one of the key parts of how this works.

See #569 for the previous issue for this.