From d0d92265140b56057a2ab4dfa7b60813b1340b80 Mon Sep 17 00:00:00 2001
From: Nick Treleaven <ntrel002@gmail.com>
Date: Tue, 2 Dec 2025 16:57:01 +0000
Subject: [PATCH] [spec/expression] Improve placement `new` docs

Rename subheading *Placement New*.
Add grammar link.
Remove 'PlacementExpression can be a dynamic array' - see
https://github.com/dlang/dmd/issues/22164.
Fix paragraph tag for class PlacementExpression.
Use list for restrictions.
PlacementExpression type must be mutable and not `shared`.
---
 spec/expression.dd | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/spec/expression.dd b/spec/expression.dd
index 07d951b388..7791ab9c5f 100644
--- a/spec/expression.dd
+++ b/spec/expression.dd
@@ -3094,9 +3094,9 @@ $(H4 $(LNAME2 new_multidimensional, Multidimensional Arrays))
         }
         -----------
 
-$(H4 $(LNAME2 placement-expression, Placement Expression))
+$(H4 $(LNAME2 placement-expression, Placement New))
 
-    $(P The $(I PlacementExpression) explicitly provides the storage for $(I NewExpression) to initialize with
+    $(P The $(GLINK PlacementExpression) explicitly provides the storage for $(I NewExpression) to initialize with
     the newly created value, rather than using the $(DDLINK spec/garbage, Garbage Collection, garbage
     collected) heap.)
 
@@ -3105,9 +3105,6 @@ $(H4 $(LNAME2 placement-expression, Placement Expression))
 
     $(P The $(I Type) of the $(I PlacementExpression) need not be the same as the $(I Type) of the object being created.)
 
-    $(P Alternatively, the $(I PlacementExpression) can be a dynamic array, which must represent sufficient memory
-    for the object being created.)
-
     $(BEST_PRACTICE Using a static array of `void` is preferred for the $(I PlacementExpression).)
 
     $(P The lifetime of the object presented as an lvalue ends with the execution of the $(I NewExpression),
@@ -3131,7 +3128,7 @@ $(H4 $(LNAME2 placement-expression, Placement Expression))
     ---
     )
 
-    (If Type is a class, the $(I PlacementExpression) must produce an lvalue of a type that is of a
+    $(P If *Type* is a class, the $(I PlacementExpression) must produce an lvalue of a type that is of a
     sufficient size to hold the class object such as `void[__traits(classInstanceSize, Type)]`
     or a dynamic array representing sufficient memory for the class object.)
 
@@ -3152,11 +3149,16 @@ $(H4 $(LNAME2 placement-expression, Placement Expression))
     ---
     )
 
-    $(P $(I PlacementExpression)  cannot be used for associative arrays, as associative arrays
+    $(P Restrictions:)
+    $(UL
+    $(LI The $(I PlacementExpression) type must be mutable and not `shared`.)
+
+    $(LI $(I Type) cannot be an associative array, as associative arrays
     are designed to be on the GC heap. The size of the associative array allocated is determined
     by the runtime library, and cannot be set by the user.)
 
-    $(P The use of $(I PlacementExpression) is not allowed in `@safe` code.)
+    $(LI Placement `new` is not allowed in `@safe` code.)
+    )
 
     $(P To allocate storage with an allocator function such as `malloc()`, a simple template can be used:)