[SR-10487] Misleading about the swift doc.

[swift-ci]

Previous ID	SR-10487
Radar	None
Original Reporter	jwang (JIRA User)
Type	Bug

Additional Detail from JIRA

Votes	0
Component/s	Standard Library
Labels	Bug, Documentation
Assignee	None
Priority	Medium

md5: a2b9e0916b50d3b08aeae4427512a1f2

Issue Description:

for the Array method:

 @inlinable public func index(_ i: Int, offsetBy distance: Int, limitedBy limit: Int) -> Int?

the Doc gives an example:

/// let numbers = [10, 20, 30, 40, 50]
/// if let i = numbers.index(numbers.startIndex,
/// offsetBy: 4,
/// limitedBy: numbers.endIndex) {

/// print(numbers[i])

/// }

why it uses `numbers.endIndex` for the `limit` param, it obvious wrong, we should use `numbers.endIndex-1`, it works here because the `distance` param is 4, and it will crash if the `distance` is 5.

And if I search `limitedBy` in the swift project, there are a lot of places use `endIndex` as the param.

I think these are bad examples, we should fix it.

[belkadan]

cc @natecook1000, @krilnon, @lorentey