Polish changelog (#20864)

changelog/dmd.auto-ref-local.dd

@@ -1,4 +1,4 @@
-`ref` and `auto ref` can now be applied to local, static, extern, and global variables
+Storage classes `ref` and `auto ref` can now be applied to local, static, extern, and global variables
 
 For example, one can now write:
 ```

changelog/dmd.default-align.dd

@@ -1,7 +1,7 @@
-The `align` attribute now allows to specify `default` explicitly
+The `align` attribute now allows specifying `default` explicitly
 
 A lone `align` sets the alignment to the type’s default.
-Alternatively, to be more explicit, `align(default)` does the same.
+To be more explicit, `align(default)` does the same.
 
 ```
 struct S

changelog/dmd.delete-keyword.dd

@@ -1,6 +1,6 @@
-`delete` is no longer a keyword
+Remove `delete` as a keyword
 
-After being superseded by `destroy()`, deprecated, and turned into an error, the keyword can now be used as an identifier:
+After being superseded by `destroy()`, deprecated, and turned into an error, `delete` can now be used as an identifier:
 
 ---
 enum Action

changelog/dmd.deprecation-case.dd

@@ -1,6 +1,6 @@
-An error is now given for case fallthough for multivalued cases
+Case fallthough for multivalued cases is an error now
 
-This used to give a deprecation, this now gives an error:
+This used to give a deprecation and now gives an error:
 ```
 int i;
 switch (0)

changelog/dmd.deprecation-dtor-fields.dd

@@ -1,4 +1,4 @@
-An error is now given for constructors with field destructors with stricter attributes
+An error is now given for constructors when a field's destructor has stricter attributes
 
 ```
 struct HasDtor

changelog/dmd.deprecation-noop-assignment.dd

@@ -1,13 +1,14 @@
 Initializing a field with itself has been deprecated
 
-This is to prevent a common mistake when typing a simple constructor, where a parameter name is misspelled:
+This is to prevent a common mistake when a field and a parameter ought to have the same name,
+but one is misspelled where it's declared:
 
 ---
 struct S
 {
     int field;
 
-    this(int feild)
+    this(int feild) // supposed to be: this(int field)
     {
         this.field = field; // equal to this.field = this.field
     }

changelog/dmd.deprecation-version-debug-number.dd

@@ -1,4 +1,5 @@
-Integers in debug or version statements have been removed from the language
+Integers in `debug` or `version` statements have been removed from the language
 
 These were deprecated in 2.101.
-Use `-debug=identifier` and `-version=identifier` instead for versions set on the command line, or `version = identifier;` and `debug = identifier;` for versions set in code at global scope.
+Use `-debug=identifier` and `-version=identifier` instead for versions set on the command line,
+and likewise `version = identifier;` and `debug = identifier;` for versions set in code at global scope.

changelog/dmd.error-messages.dd

@@ -5,30 +5,30 @@ Some changes have been made without being associated to a reported issue:
 Error messages for `@safe` violations now consistently mention they are related to `@safe` functions (or default functions with `-preview=safer`).
 In general, function attributes that failed to infer have a more compact error message:
 
----
-/*
-BEFORE:
+Before:
+$(CONSOLE
 app.d(8): Error: function `attributediagnostic_nothrow.gc1` is not `nothrow`
 app.d(2):        which wasn't inferred `nothrow` because of:
 app.d(2):        `object.Exception` is thrown but not caught
+)
 
-AFTER:
+After:
+$(CONSOLE
 app.d(8): Error: function `attributediagnostic_nothrow.gc1` is not `nothrow`
 app.d(2):        and `object.Exception` being thrown but not caught makes it fail to infer `nothrow`
-*/
----
+)
 
 Match levels are now mentioned on ambiguous overloads: [#20637](https://github.com/dlang/dmd/pull/20637)
 
----
-/*
-BEFORE:
+Before:
+$(CONSOLE
 Error: `app.bar` called with argument types `(string)` matches both:
+)
 
-AFTER:
+After:
+$(CONSOLE
 Error: `app.bar` called with argument types `(string)` matches multiple overloads after implicit conversions:
-*/
----
+)
 
 Error messages related to operator overloading have been improved.
 When the related template functions (`opUnary`, `opBinary`, `opBinaryRight`, `opOpAssign`, `opIndex`, `opSlice`)
@@ -45,18 +45,18 @@ void main()
     S s;
     const x = s[3 .. "4"];
 }
+---
 
-/*
 Before:
-
+$(CONSOLE
 app.d(6): Error: no `[]` operator overload for type `S`
+)
 
 After:
-
+$(CONSOLE
 app.d(6): Error: no `[3.."4"]` operator overload for type `S`
 app.d(1):        perhaps define `auto opSlice(int lower, string upper) {}` for `app.S`
-*/
----
+)
 
 ---
 struct Str {}
@@ -72,18 +72,19 @@ void f(Str str, Number number)
     const s = str ~ "hey";
     const n = number + "oops";
 }
+---
 
-/*
 Before:
-
+$(CONSOLE
 app.d(12): Error: incompatible types for `(str) ~ ("hey")`: `Str` and `string`
     const s = str ~ "hey";
               ^
 app.d(13): Error: incompatible types for `(number) + ("oops")`: `Number` and `string`
     const n = number + "oops";
+)
 
 After:
-
+$(CONSOLE
 app.d(12): Error: operator `~` is not defined for type `Str`
     const s = str ~ "hey";
               ^
@@ -97,10 +98,9 @@ app.d(13):        cannot pass argument `"oops"` of type `string` to parameter `i
 app.d(7):        `opBinary` defined here
     int opBinary(string op : "+")(int rhs) => this.x + x;
         ^
-*/
----
+)
 
 Furthermore:
 
 - D1 operator overloading functions (`opAdd`, `opDot`) are completely removed and no longer mentioned in error messages specifically.
-- Class allocators (`auto new() {}`) are not only a semantic error, but no longer being parsed
+- Class allocators (`auto new() {}`) are not only a semantic error, but no longer parse.

changelog/dmd.ftime-trace.dd

@@ -1,4 +1,4 @@
-Build time profiling has been added to dmd
+Build time profiling has been added to DMD
 
 The `-ftime-trace` switch that the LDC compiler already has, is now also available in dmd.
 It can be used to figure out which parts of your code take the longest to compile, so you can optimize your build times.
@@ -13,4 +13,4 @@ A different output file can be selected with `-ftime-trace-file=trace.json`.
 
 The output is in Google Chrome's profiler format, which can be viewed in an interactive viewer like [ui.perfetto.dev](https://ui.perfetto.dev).
 
-See also this YouTube tutorial: [Easily Reduce Build Times by Profiling the D Compiler](https://www.youtube.com/watch?v=b8wZqU5t9vs)
+See also the YouTube tutorial [*Easily Reduce Build Times by Profiling the D Compiler*](https://www.youtube.com/watch?v=b8wZqU5t9vs).

changelog/dmd.getBitfieldInfo.dd

@@ -1,6 +1,6 @@
-Add __traits getBitfieldOffset and getBitfieldWidth
+New traits `getBitfieldOffset` and `getBitfieldWidth` for built-in bitfields
 
-This completes the introspection capabilities of builtin bitfields. For example:
+This completes the introspection capabilities of built-in bitfields. For example:
 
 ---
 struct S

changelog/dmd.import-c-i.dd

@@ -1,3 +1,3 @@
 Using the compiler flag `-i` will now properly pick up C source files
 
-Previously you needed to manually include .c source files, it now works just like with .d files
+Previously, you needed to manually include `*.c` source files, it now works just like with D files.

changelog/dmd.import-exp-hexstring.dd

@@ -1,7 +1,7 @@
 Import expressions are now treated as hex strings
 
 While [Import expressions](https://dlang.org/spec/expression.html#import_expressions) are typed as `string`, they are also used to embed binary files.
-By treating them the same as hex strings, they will implicitly convert to arrays of integral types other than `char`.
+By treating them the same as [hex strings](https://dlang.org/spec/lex.html#hex_strings), they implicitly convert to arrays of integral types.
 
 ---
 // Formerly, a cast was required:

changelog/dmd.importc-pragma-stc.dd

@@ -2,25 +2,24 @@ A pragma for ImportC allows to set `nothrow`, `@nogc` or `pure`
 
 The following new pragma for ImportC allows to set default storage
 classes for function declarations:
-```
+```c
 #pragma attribute(push, [storage classes...])
 ```
 The storage classes `nothrow`, `nogc` and `pure` are supported.
 Unrecognized attributes are ignored.
 Enabling a default storage class affects all function declarations
 after the pragma until it is disabled with another pragma.
-Declarations in includes are also affected. The following example
+Declarations in includes are also affected.
+The changed storage classes are pushed on a stack. The last change can
+be undone with the following pragma.
+The following example
 enables `@nogc` and `nothrow` for a library:
 
-```
+```c
 #pragma attribute(push, nogc, nothrow)
 #include <somelibrary.h>
-```
-
-The changed storage classes are pushed on a stack. The last change can
-be undone with the following pragma:
-```
 #pragma attribute(pop)
 ```
+
 This can also disable multiple default storage classes at the same time,
 if they were enabled with a single `#pragma attribute(push, ...)` directive.

changelog/dmd.isCOMClass.dd

@@ -1,5 +1,5 @@
-New trait isCOMClass to detect if a type is a COM class
+New trait `isCOMClass` to detect if a type is a COM class
 
-A COM class inherits from a possibly user defined interface called ``IUnknown``.
-To detect this during compilation use the trait ``__traits(isCOMClass, Type)``.
-Or for during runtime use the ``TypeInfo_Class`` flag.
+A Component Object Model (COM) class inherits from a possibly user-defined interface named ``IUnknown``.
+To detect this during compilation, use the trait ``__traits(isCOMClass, Type)``.
+During runtime, use the ``TypeInfo_Class`` flag.

changelog/dmd.obj_extensions.dd

@@ -1,6 +1,6 @@
 Object file extensions `.o` and `.obj` are now accepted on all platforms
 
-Accepting .o and .obj file extensions on all platforms makes DMD behave
-the same as Clang and other modern compilers. There is no point in
-discarding *.o or *.obj depending on the current OS, as both extensions
-indicate that this is an object file.
+Accepting `.o` and `.obj` file extensions on all platforms makes DMD behave
+like Clang and other modern compilers. There is no point in
+discarding `*.o` or `*.obj` depending on the current operating system, as both extensions
+unambiguously denote object file.

changelog/dmd.objc-improvements.dd

@@ -1,14 +1,14 @@
-Objective-C selectors are now automatically generated when not specified with @selector.
+Objective-C selectors are now automatically generated when not specified with `@selector`.
 
 Additionally, the Objective-C selector generation rules have changed, following these steps:
-1. Functions marked with @property will generate `setXYZ:` for the setters.
-2. For property functions named with a "is" prefix, the `is` will be stripped off in the setter.
-3. Selector generation now uses the names of the function parameters instead of their D mangled types.
+1. Functions marked with `@property` will generate `setXYZ:` for the setters.
+2. For property functions with names starting with `is`, that prefix will be stripped off in the setter.
+3. Selector generation now uses the names of the function parameters instead of their D-mangled types.
 
-Selectors may still be specified with the @selector UDA, in which case it takes precedence over the
+Selectors may still be specified with the `@selector` UDA, in which case it takes precedence over the
 automatically generated selectors.
 
-These new rules apply both for extern and non-extern objective-c classes and protocols.
+These new rules apply both for `extern` and non-`extern` Objective-C classes and protocols.
 
 ---
 extern(Objective-C)
@@ -34,5 +34,5 @@ class Fox : NSObject {
 }
 ---
 
-These changes should not break any existing code as the automatic selector generation
-was not present before. And automatic selector generation only applies to extern(Objective-C) methods.
+These changes should not break any existing code because the automatic selector generation
+was not present before. And automatic selector generation only applies to `extern(Objective-C)` methods.

changelog/dmd.oq-compiler-switch.dd

@@ -1,6 +1,6 @@
-Add `-oq` switch to DMD
+New compiler switch `-oq` for DMD
 
-The switch gives fully qualified names to object files, preventing name conflicts when using the `-od` switch
+The switch gives fully qualified names to object files, preventing name conflicts when using the switch `-od`
 while compiling multiple modules with the same name, but inside different packages.
 The switch already existed in LDC, but is now in dmd as well.
 
@@ -12,4 +12,4 @@ dmd -c -oq -od=. app.d util/app.d misc/app.d
 
 This will output `app.obj`, `util.app.obj`, and `misc.app.obj`, instead of just `app.obj`.
 
-`-oq` also applies to other outputs, such as DDoc (`-D -Dd=.`) and .di header generation (`-H -Hd=.`).
+The switch `-oq` also applies to other outputs, such as Ddoc (`-D -Dd=.`) and `.di` header generation (`-H -Hd=.`).

changelog/dmd.postfix-this-attributes.dd

@@ -1,6 +1,6 @@
 Postfix type qualifier method attributes for `-H` and `-D`
 
-`.di` interface file generation and Ddoc output will now have type qualifier
+The `.di` interface file generation and Ddoc output will now have type qualifier
 attributes placed after the parameter list for methods (and constructors).
 This avoids confusion with the return type.
 

changelog/dmd.remove-samples.dd

@@ -1,6 +1,6 @@
-The 'samples' folder has been removed from DMD installations
+The folder *samples* has been removed from DMD installations
 
-Every DMD release would include a 'samples' folder with small D code examples.
+Every DMD release has included a folder with small D code examples.
 These examples are quite old, and not a good representation of modern D.
 They're also hard to discover, since D compilers are often installed through an installer or package manager.
 

changelog/dmd.rvalue.dd

@@ -1,9 +1,13 @@
-Add primary expression of the form `__rvalue(expression)` which causes `expression` to be treated as an rvalue, even if it is an lvalue.
+New keyword `__rvalue`
+
+The newly added primary expression of the form `__rvalue(expression)`
+evaluates to `expression`, except that it is treated as an rvalue,
+even if would be an lvalue otherwise.
 
 Overloads on `ref`:
 ```
-foo(S s); // selected if `s` is an rvalue
-foo(ref S s); // selected if argument `s` is an lvalue
+foo(    S s); // selected if the argument is an rvalue
+foo(ref S s); // selected if the argument is an lvalue
 
 S s;
 S bar();
@@ -11,7 +15,7 @@ S bar();
 foo(s); // selects foo(ref S)
 foo(bar()); // selects foo(S)
 ```
-With this change,
+With this change:
 ```
 foo(__rvalue(s)); // selects foo(S)
 ```

changelog/dmd.safer.dd

@@ -19,4 +19,4 @@ void main()
 }
 ---
 
-For more information, see: [safer.md](https://github.com/WalterBright/documents/blob/38f0a846726b571f8108f6e63e5e217b91421c86/safer.md)
+For more information, see [this document](https://github.com/WalterBright/documents/blob/38f0a846726b571f8108f6e63e5e217b91421c86/safer.md).

changelog/dmd.shortened-method-constructor.dd

@@ -1,6 +1,6 @@
 Shortened method syntax can now be used in constructors
 
-This used to raise an error "cannot return expression from constructor", but it's now supported:
+This used to raise an error (cannot return expression from constructor), but is now supported:
 
 ---
 struct Number

changelog/dmd.unsafe-boolean-values.dd

@@ -1,4 +1,4 @@
-`bool` values other than 0 or 1 are not `@safe`
+For type `bool`, values other than 0 or 1 are not `@safe`
 
 The spec [was updated](https://dlang.org/spec/type.html#bool)
 (for 2.109) so that only 0 and 1 are
@@ -7,7 +7,7 @@ for `bool`. This means that reading a `bool` value whose underlying byte represe
 has other bits set is implementation-defined and should be avoided.
 Consequently the following are deprecated in `@safe` code:
 
-* `void` initialization of booleans (since 2.109)
+* initialization of `bool` variables with `= void` (since 2.109)
 * Reading a `bool` field from a union (since 2.109)
 * Runtime casting a dynamic array to a `bool` dynamic array type
 * Runtime casting a `bool` dynamic array to a tail mutable dynamic array type

changelog/druntime.bcrypt.dd

@@ -1,5 +1,7 @@
 Add Windows BCrypt bindings under `core.sys.windows.bcrypt`
 
-Adds full [BCrypt API](https://learn.microsoft.com/en-us/windows/win32/api/bcrypt/) bindings to the Windows-specific system bindings.
+Adds full [BCrypt API](https://learn.microsoft.com/en-us/windows/win32/api/bcrypt/) bindings
+to the Windows-specific system bindings.
 
-The Windows-specific bindings under `core.sys.windows.sdkddkver` and `core.sys.windows.w32api` have also been updated in order to facilitate the creation of the BCrypt bindings.
+The Windows-specific bindings under `core.sys.windows.sdkddkver` and `core.sys.windows.w32api`
+have also been updated in order to facilitate the creation of the BCrypt bindings.

changelog/druntime.criticalRegionLock.dd

@@ -1,5 +1,5 @@
-Remove criticalRegionLock
+Remove `criticalRegionLock`
 
-The criticalRegionLock feature suffer from a serious design flaw: $(LINK https://issues.dlang.org/show_bug.cgi?id=24741)
+The `criticalRegionLock` feature suffer from a serious design flaw: $(LINK https://issues.dlang.org/show_bug.cgi?id=24741)
 
 It turns out it is not used, so rather than fixing the flaw, the feature was removed.

changelog/druntime.expect-trap.dd

@@ -1,7 +1,7 @@
-Adds `expect`, `[un]likely`, `trap` to `core.builtins`
+Adds `expect`, `likely`, `unlikely`, and `trap` to `core.builtins`
 
 Adds the functions `expect` and `likely`/`unlikely` for branch and value hints for the LDC/GDC compilers.
 DMD ignores these hints.
 
-Adds `trap` to lowered to the target dependent trap instruction.
-If the target does not have a trap instruction, this intrinsic will be lowered to the call of the `abort()` function.
+Adds the function `trap` to be lowered to the target-dependent trap instruction.
+If the target does not have a trap instruction, this intrinsic will be lowered to a call of the `abort` function.

changelog/druntime.segfault-message.dd

@@ -12,14 +12,14 @@ $(CONSOLE
 [1]    37856 segmentation fault (core dumped)  ./app
 )
 
-In order to find the cause of the error, the program needs to be run again in a debugger like gdb.
+In order to find the cause of the error, the program needs to be run again in a debugger like GDB.
 
 There is the `registerMemoryErrorHandler` function in `etc.linux.memoryerror`, which catches `SIGSEGV` signals and transforms them into a thrown `InvalidPointerError`, providing a better message.
 However, it doesn't work on call stack overflow, because it uses stack memory itself, so the segfault handler segfaults.
 It also relies on inline assembly, limiting it to the x86 architecture.
 
 A new function `registerMemoryAssertHandler` has been introduced, which does handle stack overflow by setting up an [altstack](https://man7.org/linux/man-pages/man2/sigaltstack.2.html).
-It uses `assert(0)` instead of throwing an `Error` object, so the result corresponds to the chosen `-checkaction=[D|C|halt|context]` setting.
+It uses `assert(0)` instead of throwing an `Error` object, so the result corresponds to the chosen `-checkaction` setting.
 
 Example: