Fixes example snippets in Array.swift considering endianness

[valeriyvan]

Fixes example snippets in Array.swift considering endianness

[airspeedswift]

@swift-ci please smoke test

[valeriyvan]

ping

[valeriyvan]

ping

[xwu]

Does Swift have any officially supported big endian platforms?

I think it would be sufficient to include the clarification about little endianness without detailing what the big endian result would be, especially if it’s not actually possible to use Swift to obtain that result.

I also think it’s fine to leave out any mention of Apple platforms, since it’s not as though little endian systems are particularly common for Apple platforms but not for others.

Instead, it might be good to find a reputable didactic page that defines “little endian” and link to it.

[valeriyvan]

Fixed

[xwu]

A good improvement. I've just got some additional thoughts.

[xwu]

This is better, but I think it could be still more improved if (a) this is an actual link; and (b) it refers to a source that is more vetted--since the Wikipedia article is tagged "This article has multiple issues" (which is not a good look for a reference)--and more concise--since the Wikipedia article is also many times longer than this documentation and contains more than any user would need to look up to understand this documentation.

Before we start, there is one other problem to fix along the way: Someone else fixed the example so that numbers is of type [Int32] instead of [Int] so that word size doesn't matter. This is very good for didactic purposes; we do not need to teach someone about word size in this place, so let's not do so. However, they forgot to fix the text that preceded it, so it still says "numbers, an array of Int"--this is incorrect and needs to be fixed to say "an array of Int32".

Here is what I would suggest: Remove the clarifying information here from this line and introduce it in the text that introduces the example like this:

The following example copies bytes from the byteValues array into numbers, an array of Int32; on a little-endian machine, the result is as shown:

Now, what resource might be a good one for defining endianness? A quick Google search shows a very readable and accurate definition at MDN. It covers essentially everything a reader of this documentation might need to know, and crucially, very little that a reader wouldn't need to know. I like it, but perhaps you might prefer something similar from a different source; just make sure that it is concise, written at an appropriate level, and vetted.

[valeriyvan]

(a) this is an actual link

should it be <a href="https://developer.mozilla.org/en-US/docs/Glossary/Endianness/">little-endian</a> or [little-endian](https://developer.mozilla.org/en-US/docs/Glossary/Endianness/)?

[xwu]

Let's do the same thing here as for the example above.

First, let's take word size out of the equation, because it is irrelevant to this documentation. Instead, let's make numbers of type [Int32] just like another person did above. Then, let's take the information about endianness out of the comment-within-a-comment and make it a real link, and put that in the introductory remarks, something like:

The following example copies the bytes of the numbers array into a buffer of UInt8; on a little-endian machine, the result is as shown:
[...]
// byteBuffer == [1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0]

[amartini51]

Thanks for the PR! This is improvement, but I had a couple questions for you.

[amartini51]

This would be the first link to Mozilla developer documentation in the repository. Elsewhere, we have links to Wikipedia. Would this article work instead?

https://en.wikipedia.org/wiki/Endianness

EDIT: I now see @xwu asked you previously to change it from this link to something else. We might need more discussion around this point.

[amartini51]

I asked one of the editors about this link in the context of the writing style we use in documentation. To follow that style, like the rest of the standard library documentation aims to do, we should omit the link.

[valeriyvan]

I am not sure I understand. Should link be removed???

[amartini51]

Yes.

[valeriyvan]

Done

[xwu]

LGTM!

[amartini51]

Looks good to me, thank you!

[xwu]

@swift-ci smoke test and merge