[swift-dev] Documentation for Int and UInt is misleading

[Ole Begemann]

Int and UInt have different sizes on 32-bit and 64-bit platforms. The documentation for Int currently says this, however:

"Int: A 64-bit signed integer value type."
(https://developer.apple.com/library/prerelease/ios/documentation/Swift/Reference/Swift_Int_Structure/index.html)

I was caught off guard by this twice in the last few months, so I'd like to improve the docs and say something like this:

"Int: A signed integer value type that has the same size as the current platform's native word size. On a 32-bit platform, Int is the same size as Int32. On a 64-bit platform, Int is the same size as Int64."

(Taken word for word from The Swift Programming Language at https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/TheBasics.html#//apple_ref/doc/uid/TP40014097-CH5-ID309.)

The documentation comment is currently generated for all integer types in stdlib/public/core/FixedPoint.swift.gyb (https://github.com/apple/swift/blob/671eb1f4dd3c19c7cbf39ec017ef16f0a5cb3c2e/stdlib/public/core/FixedPoint.swift.gyb#L182-L183), so we would need to add a conditional there and handle Int and UInt separately.

Before I proceed to do that, I wanted to ask if it would be a welcome change. If you have suggestions on how to word this better, I'd love to hear them.

–Ole