Improvements to docs and text

* docs(std.math): elaborate on difference between absCast and absInt

* docs(std.rand.Random.weightedIndex): elaborate on likelihood

I think this makes it easier to understand.

* langref: add small reminder

* docs(std.fs.path.extension): brevity

* docs(std.bit_set.StaticBitSet): mention the specific types

* std.debug.TTY: explain what purpose this struct serves

This should also make it clearer that this struct is not supposed to provide unrelated terminal manipulation functionality such as setting the cursor position or something because terminals are complicated and we should keep this struct simple and focused on debugging.

* langref(package listing): brevity

* langref: explain what exactly `threadlocal` causes to happen

* std.array_list: link between swapRemove and orderedRemove

Maybe this can serve as a TLDR and make it easier to decide.

* PrefetchOptions.locality: clarify docs that this is a range

This confused me previously and I thought I can only use either 0 or 3.

* fix typos and more

* std.builtin.CallingConvention: document some CCs

* langref: explain possibly cryptic names

I think it helps knowing what exactly these acronyms (@clz and @ctz) and
abbreviations (@popCount) mean.

* variadic function error: add missing preposition

* std.fmt.format docs: nicely hyphenate

* help menu: say what to optimize for

I think this is slightly more specific than just calling it
"optimizations". These are speed optimizations. I used the word
"performance" here.

1 files changed, 4 insertions, 3 deletions

diff --git a/lib/std/math.zig b/lib/std/math.zig
index 14c71a796f..02b737610c 100644
--- a/lib/std/math.zig
+++ b/lib/std/math.zig
@@ -782,7 +782,8 @@ fn testOverflow() !void {
 }
 
 /// Returns the absolute value of x, where x is a value of a signed integer type.
-/// See also: `absCast`
+/// Does not convert and returns a value of a signed integer type.
+/// Use `absCast` if you want to convert the result and get an unsigned type.
 pub fn absInt(x: anytype) !@TypeOf(x) {
     const T = @TypeOf(x);
     return switch (@typeInfo(T)) {
@@ -1015,8 +1016,8 @@ pub inline fn fabs(value: anytype) @TypeOf(value) {
 }
 
 /// Returns the absolute value of the integer parameter.
-/// Result is an unsigned integer.
-/// See also: `absInt`
+/// Converts result type to unsigned if needed and returns a value of an unsigned integer type.
+/// Use `absInt` if you want to keep your integer type signed.
 pub fn absCast(x: anytype) switch (@typeInfo(@TypeOf(x))) {
     .ComptimeInt => comptime_int,
     .Int => |int_info| std.meta.Int(.unsigned, int_info.bits),