From 4132c6a65f891c9eabb937abfcfc2adc5cf45936 Mon Sep 17 00:00:00 2001
From: josh11b <15258583+josh11b@users.noreply.github.com>
Date: Thu, 20 Jun 2024 14:17:25 -0700
Subject: [PATCH] Merge the suffix ops into a single box in the operator
 precedence mermaid diagram (#4067)

The current approach was done to work-around a limitation that we can
only have a single link per box, but is unscalable. Instead have a
single link to a new sections of the document that describes the box,
and has multiple links.

---------

Co-authored-by: Josh L <josh11b@users.noreply.github.com>
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
---
 docs/design/expressions/README.md | 49 ++++++++++++++++++-------------
 1 file changed, 29 insertions(+), 20 deletions(-)

diff --git a/docs/design/expressions/README.md b/docs/design/expressions/README.md
index 39ba34f37418e..fb5de9f547f02 100644
--- a/docs/design/expressions/README.md
+++ b/docs/design/expressions/README.md
@@ -16,6 +16,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
     -   [Unqualified names](#unqualified-names)
     -   [Qualified names and member access](#qualified-names-and-member-access)
 -   [Operators](#operators)
+-   [Suffix operators](#suffix-operators)
 -   [Conversions and casts](#conversions-and-casts)
 -   [`if` expressions](#if-expressions)
 -   [Numeric type literal expressions](#numeric-type-literal-expressions)
@@ -63,19 +64,13 @@ graph BT
 
     top((" "))
 
-subgraph memberCallIndex[" "]
-    direction LR
-    memberAccess{"x.y<br>
-                  x.(...)<br>
-                  x->y<br>
-                  x->(...)"}
-    click memberAccess "https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/expressions/member_access.md"
-
-    callAndIndexing{"x(...)<br>
-                     x[y]"}
-    click callAndIndexing "https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/expressions/indexing.md"
-end
-style memberCallIndex fill:none
+    suffixOps{"x.y<br>
+               x.(...)<br>
+               x->y<br>
+               x->(...)<br>
+               x(...)<br>
+               x[y]"}
+    click suffixOps "https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/expressions/README.md#suffix-operators"
 
     constType["const T"]
     click pointer-type "https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/expressions/type_operators.md"
@@ -156,20 +151,17 @@ style memberCallIndex fill:none
 
     top --> parens & braces & unqualifiedName
 
-    memberCallIndex --> top
-
-    callAndIndexing --> memberAccess
-    memberAccess --> callAndIndexing
+    suffixOps --> top
 
-    constType --> memberCallIndex
+    constType --> suffixOps
     pointerType --> constType
     as --> pointerType
 
-    pointer --> memberCallIndex
+    pointer --> suffixOps
     negation & complement & incDec --> pointer
     unary --> negation & complement
     %% Use a longer arrow here to put `not` next to `and` and `or`.
-    not -------> memberCallIndex
+    not -------> suffixOps
     as & multiplication & modulo & bitwise_and & bitwise_or & bitwise_xor & shift --> unary
     addition --> multiplication
     comparison --> as & addition & modulo & bitwise_and & bitwise_or & bitwise_xor & shift
@@ -345,6 +337,23 @@ The binary arithmetic and bitwise operators also have
 [compound assignment](/docs/design/assignment.md) forms. These are statements
 rather than expressions, and do not produce a value.
 
+## Suffix operators
+
+These operators act like unary postfix operators for purposes of precedence:
+
+-   [Member access operators](member_access.md), like `x.y` and the
+    dereferencing variant `x->y`, only have an expression on their left-hand
+    side. The right-hand side is a name.
+-   The [compound member access operators](member_access.md), `x.(...)` and
+    `x->(...)`, have an expression as their second operand, but put that
+    expression in parentheses and so it doesn't participate in the precedence
+    considerations of its first operand.
+-   The [indexing operator](indexing.md), `x[y]`, similarly puts its second
+    operand in matching square brackets.
+-   The call operator, `x(...)`, takes a comma-separated list of arguments, but
+    again puts them in parentheses that clearly separate them for precedence
+    purposes.
+
 ## Conversions and casts
 
 When an expression appears in a context in which an expression of a specific