Documentation for Int and UInt is misleading


(Ole Begemann) #1

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


(Dave Abrahams) #2

Absolutely, it would be welcome. Please submit a pull request!

···

on Mon Feb 08 2016, Ole Begemann <swift-dev-AT-swift.org> wrote:

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.

--
-Dave


(Ole Begemann) #3

Done: https://github.com/apple/swift/pull/1249.

My first pull request, suggestions for improvement welcome.

···

On 08 Feb 2016, at 14:56, Dave Abrahams via swift-dev <swift-dev@swift.org> wrote:

Absolutely, it would be welcome. Please submit a pull request!