langref: clarify functionality of the round builtin (#19503)

A test has also been added to demonstrate the expected behavior.

* std.math: update round doc comment to match the builtin

Author: torque

doc/langref.html.in

@@ -5618,9 +5618,11 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
       {#header_open|@round#}
       <pre>{#syntax#}@round(value: anytype) @TypeOf(value){#endsyntax#}</pre>
       <p>
-      Rounds the given floating point number to an integer, away from zero. Uses a dedicated hardware instruction
-      when available.
+      Rounds the given floating point number to the nearest integer. If two integers are equally close, rounds away from zero.
+      Uses a dedicated hardware instruction when available.
       </p>
+      {#code|test_round_builtin.zig#}
+
       <p>
       Supports {#link|Floats#} and {#link|Vectors#} of floats.
       </p>

doc/langref/test_round_builtin.zig

@@ -0,0 +1,10 @@
+const expect = @import("std").testing.expect;
+
+test "@round" {
+    try expect(@round(1.4) == 1);
+    try expect(@round(1.5) == 2);
+    try expect(@round(-1.4) == -1);
+    try expect(@round(-2.5) == -3);
+}
+
+// test

lib/std/math.zig

@@ -1140,7 +1140,8 @@ test ByteAlignedInt {
     try testing.expect(ByteAlignedInt(u129) == u136);
 }
 
-/// Rounds the given floating point number to an integer, away from zero.
+/// Rounds the given floating point number to the nearest integer.
+/// If two integers are equally close, rounds away from zero.
 /// Uses a dedicated hardware instruction when available.
 /// This is the same as calling the builtin @round
 pub inline fn round(value: anytype) @TypeOf(value) {