[stdlib] Revise and expand floating-point documentation

[natecook1000]

What's in this pull request?

Expanded documentation for FloatingPoint, BinaryFloatingPoint, and the conforming types.

Resolved bug number: n/a

---

Before merging this pull request to apple/swift repository:

• Test pull request on Swift continuous integration.

Triggering Swift CI

The swift-ci is triggered by writing a comment on this PR addressed to the GitHub user @swift-ci. Different tests will run depending on the specific comment that you use. The currently available comments are:

Smoke Testing

Platform	Comment
All supported platforms	@swift-ci Please smoke test
All supported platforms	@swift-ci Please smoke test and merge
OS X platform	@swift-ci Please smoke test OS X platform
Linux platform	@swift-ci Please smoke test Linux platform

A smoke test on macOS does the following:

1. Builds the compiler incrementally.
2. Builds the standard library only for macOS. Simulator standard libraries and
   device standard libraries are not built.
3. lldb is not built.
4. The test and validation-test targets are run only for macOS. The optimized
   version of these tests are not run.

A smoke test on Linux does the following:

1. Builds the compiler incrementally.
2. Builds the standard library incrementally.
3. lldb is built incrementally.
4. The swift test and validation-test targets are run. The optimized version of these
   tests are not run.
5. lldb is tested.

Validation Testing

Platform	Comment
All supported platforms	@swift-ci Please test
All supported platforms	@swift-ci Please test and merge
OS X platform	@swift-ci Please test OS X platform
OS X platform	@swift-ci Please benchmark
Linux platform	@swift-ci Please test Linux platform

Lint Testing

Language	Comment
Python	@swift-ci Please Python lint

Note: Only members of the Apple organization can trigger swift-ci.

[natecook1000]

@swift-ci Please smoke test

[gottesmm]

@stephentyrone Hows this look?

[stephentyrone]

I reviewed these changes internally already; I'll go through this pull request as well as a sanity check, but based on what I've already seen this doesn't need to wait on my approval. As far as I'm concerned, this should be merged now.

[gottesmm]

Ok. SGTM!

[natecook1000]

Thanks @stephentyrone and @gottesmm! I'll watch for comments on this PR and catch them in the next batch of revisions.

[stephentyrone]

@natecook1000 The only thing that jumped out at me is that I believe the exponent is required for hexadecimal floating-point literals, but you describe it as being optional. If you can spare a couple minutes to fix that up, it would be great.

[natecook1000]

@stephentyrone It's optional in string -> floating-point conversions, where it's assumed as 0 if missing.

(swift) Double("0x10.8")
// r0 : Double? = Optional(16.5)

I don't think I discussed hexadecimal numeric literals—do you see any specific places where I'm doing that? I should probably spell "hexadecimal" correctly, though. 😳

[stephentyrone]

Hmmm. That should probably be a stdlib bug, then; init(String) should use the same format as we do for literals unless there's a good reason not to, and I don't know of other languages that allow hex float without an exponent. I'll look into this in the morning.