Swift is a relatively young language (ten years) and ~3 years ago a lot of things were brand new or had relatively recently been refactored. Also Apple released it to the public before it was really finished - and did the final work finishing off the language out in the open with collaboration as any well run open source project should be developed.

For the first five years or so it was barely ready for production use in my opinion, and it sounds like tried to use it when it was ready but still had a bit of rough edges such as docuemntation.

For example async/await was added around when you looked into it and that obviously made a lot of documentation relating to threads out of date (from memory they pretty much deleted all of it and started the long process of rewriting it, beginning with very basic docs to get broad coverage before having detailed coverage).

And before that the unicode integration wasn’t quite right yet — they did the tough work to make this work (most of these characters are multiple bytes long):

let greeting = "Hello, 🌍! こんにちは! 🇮🇳"

for character in greeting {
    print(character)
}

And this evaluates to true even though the raw data of the two strings are totally different:

let eAcute: Character = "\u{E9}" // é
let combinedEAcute: Character = "\u{65}\u{301}" // e followed by  ́

if eAcute == combinedEAcute {
    print("Both characters are considered equal.")
}

I hated how strings were handled in the original Swift, but it’s great now. Really hard to write documentation when fundamentals like that are changing. These days though, swift is very stable and all the recent changes have been new features that don’t affect existing code (or already written documentation). For example in 2023 they added Macros - essentially an inline function (your function won’t be compiled as an actual function - the macro code will be embedded in place where it’s “called”).

You define a Macro like this:

macro func assertNotNil(_ value: Any?, message: String) {
    if value == nil {
        print("Assertion failed: \(message)")
    }
}

And then if you write this code:

assertNotNil(optionalValue, message: "optionalValue should not be nil")

… it will compile as this:

if optionalValue == nil {
    print("Assertion failed: optionalValue should not be nil")
}

Notice it doesn’t even do any string interpolation at runtime. All of that happens at compile time! Cool stuff although it’s definitely a tool you can shoot yourself in the foot with.