[stdlib] Revise InlineArray documentation

[xwu]

Update documentation for InlineArray to include examples with type sugar, reword to avoid certain jargon that may be unfamiliar to some standard library users, and incorporate additional details mostly drawn from the proposal text.

[benrimmington]

Thank you very much for working on this. I have a few suggestions, but overall you've greatly improved the documentation.

---

Should it be stated that the [count of Element] shorthand is preferred?

Array:

Shortened forms are preferred

TSPL — Collection Types:

Although the two forms are functionally identical, the shorthand form is preferred

---

Should the other example code in this file also be updated?

-  ///     InlineArray<4, Int> { 1 << $0 }  //-> [1, 2, 4, 8]
+  ///     [4 of Int] { 1 << $0 }  //-> [1, 2, 4, 8]

-  ///     InlineArray<4, Int>(first: 1) { $0 << 1 }  //-> [1, 2, 4, 8]
+  ///     [4 of Int](first: 1) { $0 << 1 }  //-> [1, 2, 4, 8]

[xwu]

Some of the doc comments on specific APIs could do with some follow-on revision. I've updated the two code examples you pointed out both to incorporate the shorthand and to illustrate their differences in terms of what the closure argument is. I'll leave the more prescriptive point about whether one should prefer one spelling or another for the type to others in the future.

[xwu]

@swift-ci smoke test

[xwu]

@stephentyrone Would you or one of the other code owners, and/or the documentation folks, like to weigh in before merge?

[natecook1000]

Thanks, @xwu – these are great improvements! Re: shortened syntax – that preference is really only when used in type position. When used as an initializer, the documentation style is to prefer the type name (e.g. let fives = Array(repeating: 5, count: 5)), so those examples could be switched back.

I've also requested a review from @amartini51 👍🏻

[amartini51]

Some minor clean-up, but this looks like an improvement to me.

[xwu]

@swift-ci smoke test

[xwu]

@swift-ci smoke test Windows platform

[xwu]

@swift-ci please clean smoke test macos platform