A pice of suggestion to the swift document

Using Swift
1

I'm reading Swift Document. It seemd to be so hard for a new learner to understand how Error Handling works:
https://docs.swift.org/swift-book/documentation/the-swift-programming-language/thebasics/#Error-Handling
The example in the document:

func makeASandwich() throws {
    // ...
}


do {
    try makeASandwich()
    eatASandwich()
} catch SandwichError.outOfCleanDishes {
    washDishes()
} catch SandwichError.missingIngredients(let ingredients) {
    buyGroceries(ingredients)
}

Thanks to the help of AI, I found that it is necessary for us to IMPORT "Foundation" before trying the examples.

=w=
=w=2160×1620 222 KB

You know,the document should make it easier to understand...

2

NSError is part of Foundation. The native Swift equivalent, without using Foundation, would be Error. You have to create your own error values (usually in a struct or enum) since the native Swift equivalent is a protocol.

The last sentence of that section gives a little hint about more info:

Nevertheless, I usually always agree that the native documentation and tutorials (especially for the weblooking at you Swift Book) need better explanations, terminology and organization to effectively explain the topics to everyone.

I recommend only searching the docs if all else fails. IDE auto-completion is your best friend.

3 Likes
3

It isn't. You only need Foundation for NSError, which isn't how you typically want to create errors in Swift. A enum conforming to error is usually the preferred choice:

enum SandwichError: Error {
    case outOfCleanDishes
    case missingIngredients([String])
}
Fully compilable version for Playgrounds 
enum SandwichError: Error {
    case outOfCleanDishes
    case missingIngredients([String])
}

func makeASandwich() throws {
    // ...
}

func eatASandwich() {
    // ...
}

func washDishes() {
    // ...
}

func buyGroceries(_ ingredients: [String]) {
    // ...
}

do {
    try makeASandwich()
    eatASandwich()
} catch SandwichError.outOfCleanDishes {
    washDishes()
} catch SandwichError.missingIngredients(let ingredients) {
    buyGroceries(ingredients)
}
3 Likes
4

That’s the basics, they cover general capabilities so that you can skim through them with general notion of what the language is, then go into details with some sort of map.

The error handling is covered in detail with examples in relative chapter: Documentation

Piece of advice: don’t use AI if you just starting and want to learn the language. Invest a bit more time in learning what the official documentation has to offer or look for quality articles. It will give you much more in return. With AI you can’t validate its output due to missing knowledge on the topic, so if it suggests something wrong (and as has already been pointed out, it did so in that case already), you wouldn’t know.

3 Likes
5

the Swift Book documentation (and a lot of Swift documentation in general) is not good because the examples are not self-contained and really expect the reader to have carefully worked through all the material up to that point (or to have completed a whole different unit of the course). a tiny custom Error enum next to that example would have done a world of good, even if it were strictly “duplicating“ content in another section of the book.

i often feel we have a cultural problem of demanding too much attention from readers who in reality are trying to glean as much information as possible while investing as little time as they can. our DocC tutorials are IMAX experiences, but users are looking for TikTok videos they can watch on a side screen with the sound off.

6 Likes
6

Readers that want to learn the language want to find what they're looking for easily.

You acknowledging the documentation is not good is not justification to do nothing. DocC tutorials are not IMAX experiences. They are a tool just like anything else and their usage in the Swift Book is not optimal or consumer-friendly.

1 Like