Add note about creating arrays using newobj (#90070)

Contributes to #90038

diff --git a/docs/design/specs/Ecma-335-Augments.md b/docs/design/specs/Ecma-335-Augments.md
index bdebd1d..6dd9a81 100644 (file)
--- a/docs/design/specs/Ecma-335-Augments.md
+++ b/docs/design/specs/Ecma-335-Augments.md
@@ -20,6 +20,7 @@ This is a list of additions and edits to be made in ECMA-335 specifications. It
 - [Atomic reads and writes](#atomic-reads-and-writes)
 - [Backward branch constraints](#backward-branch-constraints)
 - [Transient pointers](#transient-pointers)
+- [Creating arrays using newobj](#creating-arrays-using-newobj)
 - [API documentation](#api-documentation)
 - [Debug Interchange Format](#debug-interchange-format)
 
@@ -1056,6 +1057,10 @@ The paragraphs mentioning "transient pointers" in section "I.12.3.2.1 The evalua
 
 Instead, note is added to sections "III.3.39 ldarga" and "III.3.44 ldloca": The arguments / local variables are stored in unmanaged memory. The address of argument / local variable can be converted to unmanaged pointer without explicit pinning.
 
+## Creating arrays using newobj
+
+Note about creating zero-based, one-dimensional arrays in section III.4.21 "newobj – create a new object" is replaced with "All zero-based, one-dimensional arrays *should* be created using newarr, not newobj". Rationale: All arrays have runtime provided constructors. It does not make sense to disallow one specific constructor just because there is more efficient alternative.
+
 ## API documentation
 
 API documentation included in partition IV: Profiles and Libraries is superseded by the actively maintained API documentation in https://github.com/dotnet/dotnet-api-docs repo. The documentation is  published at https://docs.microsoft.com/en-us/dotnet/api/.