Add grammar in docs for {f32,f64}::from_str, mention known bug.

[frewsxcv]

• Original bug about documenting grammar
  • formalize FromStr syntax #32243
• Known bug with parsing
  • Float parsing can fail on valid float literals #31407

[frewsxcv]

r? @rust-lang/docs @rust-lang/libs

[frewsxcv]

Historically, we haven't mentioned known bugs in the docs, but considering this known bug has existed for years and people keep hitting it, I think it's worth calling it out here.

[alexcrichton]

FWIW this isn't the first instance of documenting a known issue, and I think while we don't really have a policy around this the defacto policy is that "if someone cares enough to document the issue while not being willing to fix it, then seems fine to document".

[QuietMisdreavus]

I'm not a fan of including a grammar or regular expression like that, especially in the std docs. We've gradually been moving any kind of grammar into the Reference, so i would consider that a much better place for that.

As far as documenting known issues, i'm okay with it, but i think it could be better phrased:

# Known issues

In some situations, some strings that should create a valid float instead return an
error. See [issue #31407] for details.

[frewsxcv]

I'm not a fan of including a grammar or regular expression like that, especially in the std docs.

The point of this grammar is to document valid input formats for this particular standard library API. So I can get a better understanding of what you're envisioning, do you have any examples of sections in the Reference that document specific standard library APIs?

We've gradually been moving any kind of grammar into the Reference

Moving the Rust language syntax grammar to the Reference makes sense to me since it's documenting the behaviors of the language itself, as opposed to a specific standard library API

but i think it could be better phrased:

Thanks for the suggestion! I'll update it to reflect your wording

[QuietMisdreavus]

do you have any examples of sections in the Reference that document specific standard library APIs?

There's a "Special types and traits" page that seems to document some of the more-common items from the standard library.

But i think i get your point. Since this is library code, it makes sense to document it here. (Though i'm not sure if we ever got together a better documentation of all type conversion functionality than the std::convert module docs, and that doesn't even include the FromStr trait being documented here...)

There is a grammar for floating-point literals in the reference; does this match the regular expression you've entered there? I guess it wouldn't include the type suffix, but i think everything else matches?

[frewsxcv]

but i think everything else matches?

A few other differences come to mind:

• float literals, like integer literals, can have underscores
• float literals require a decimal point
• float literals can't have a leading +

[frewsxcv]

Also looks like float literals can have a capital E in the exponent part

[QuietMisdreavus]

cc @rust-lang/wg-grammar - I think some people in there aren't in the docs group on github.

[Centril]

@QuietMisdreavus I'm not sure what the ping (wg-grammar) was for; can you elaborate?

[QuietMisdreavus]

@Centril We talked about it on Discord, but my question was effectively "does the grammar WG care about the grammar of library functions", which turns out to be "not officially".

@frewsxcv Coming back to this, it's fine to have it here, but i find the regex a little hard to read. Can you convert it to BNF? I think that's a little easier to decode at a glance if you're not familiar with the syntax.

[frewsxcv]

Here's my attempt at writing out the grammar using W3C's EBNF syntax:

Float  ::= Sign? ( 'inf' | 'NaN' | Number )
Number ::= ( Digit+ |
             Digit+ '.' Digit* |
             Digit* '.' Digit+ ) Exp?
Exp    ::= [eE] Sign? Digit+
Sign   ::= [+-]
Digit  ::= [0-9]

It can be visualized here. Thoughts? Is this more clear than the regex?

[Centril]

Picking someone from T-libs randomly...

r? @Kimundi

[frewsxcv]

Anyone on the libs team have any concerns about this?

[jkordish]

ping from triage. @Kimundi have you had time to review?

[QuietMisdreavus]

I think this looks good, thanks so much! Barring any objections from @rust-lang/libs, i think this is ready to go. I'll go ahead and push this forward, but feel free to back it out if there's a problem.

@bors r+ rollup

[bors]

📌 Commit 8af02fa has been approved by QuietMisdreavus