doc: dash used instead of minus in mathematical expressions

[tspiteri]

The minus sign in mathematical expressions for i*::MIN, i*::MAX and u*::MAX is rendered using U+002D (see images below). U+002D looks bad in that context; U+2212 is more suitable and looks better in mathematical expressions.

Note: I had already opened PR #90777 to fix this, but it was closed. I opened the issue to discuss this here instead of in an already-closed PR. The reason given for closing is:

In Rust, negative numbers are expressed using U+002D HYPHEN-MINUS, and our documentation should be consistent with Rust code, rather than using a confusingly similar symbol.

But I don't agree with that: here the minus sign is in a mathematical expression that is not code. If it were an expression in verbatim code then yes, U+002D would be better, but for example −2³¹ cannot be written in code anyway (the code -2i32.pow(31) wouldn't even work).

[wooster0]

CC @joshtriplett

Now I'm less confused. You are making a good point. I think there are a few options here:

1. Write it as -2_i64.pow(31)? Although the different type might be confusing.
2. -2_i64.pow(31) as i32? It might be too long.
3. Change it to U+2212? I think using a special character like that makes it harder for others to conform to this style because it's not as easy to type and easy to mistake for the - that's easy to type.
4. Change it to U+002D? It's easy to type and most people will probably use this one but I agree that U+2212 kind of is more suitable for mathematical expressions.

I think what we ultimately need is a documentation guide for mathematical expressions, or even better (or rather in addition) a way to write -2.pow(31) in the doc comment and then have the markdown renderer automatically convert it to −2³¹. The idea is that type annotation wouldn't be needed in such special doc comment math expression. Maybe it could look like

/// The smallest value that can be represented by this integer type, <`-2.pow(31)`>.

or something like that.
But I think a complete documentation guide that everyone is actively encouraged to follow is a good first step for documentation consistency.

But ultimately there is generally tons of inconsistency in documentation and I think it's pretty much normal, especially in such a large project. So maybe it's fine to just merge those occasional fixup PRs like #90777 to keep some consistency.

[tspiteri]

Options 1 and 2 are not really something I'd ever go for. When I wrote -2i32.pow(31) my point was to emphasize that the expression wasn't code; those code expressions would not make the MIN and MAX documentation any easier to read and understand, rather the opposite.

[nagisa]

I would argue that using MathML would be ideal in terms of presentation here. If we wanted to utilize math expressions at scale in our documentations, adding support for (la-)tex-like math to our markdown-html converter would also make some sense.

Sadly neither are easy fixes – MathML isn't super widely supported out-of-the-box and the latter feature is effectively a pandoc exclusive feature AFAIK.