swift-book
swift-book copied to clipboard
apple
Add a list of language features to the reference
Is your feature request related to a problem? Please describe
As a new learner and developer, I was only able to get a limited introduction to the language through The Swift Programming Language, but there were many advanced features I couldn't learn from this document. For example, there are only a few words about Actors, and when I searched the web for tutorials, I learned that there are keywords like nonisolated. I couldn't find it in the reference document, but finally found it through a search engine in swift-evolution, where I found the proposal Improved control over actor isolation, which was implemented in 2021. I think all this is very difficult for beginner language learners.
Describe the solution you'd like
I would like to have a full list of language features in the Language Reference section of The Swift Programming Language for querying. Just like Rust's official reference document is very detailed, no matter whether the feature is newly included or not.
Describe alternatives you've considered
Update Language Guide in time just like Rust Book.
Or maintain a cheat sheet.
Additional context
Is this issue still available @dempseyatgithub ? I would like to work on it
@yakatyansh This issue needs to move https://github.com/apple/swift-book, since that project is responsible for The Swift Programming Language book.
From the ReadMe of https://github.com/apple/swift-book:
A formal contribution process for this document is still in development. In the meantime, start a pitch thread in the Swift forums for larger changes to discuss your approach and identify possible issues before you invest a lot of time in writing.
In the meantime, I will try to see what needs to be done to move this issue.
This issue looks like it's about two things: The book isn't complete, and the book doesn't include a list or index of language features by name.
The fact that TSPL isn't complete is a known issue, and unlikely to be solved by one "umbrella" Github issue. I'm starting an audit of Swift Evolution proposals, to open issues here for each proposal that didn't get corresponding documentation updates. In addition to those, we can use Github issues to track specific topics that come from multiple SE proposals and aren't covered fully — for example, to note that actors needs more detail. (See also this work-in-progress branch about distributed actors.)
The idea of a list of language features by name might be interesting. If that's the focus, I suggest we start that discussion with a forum pitch. Describing the goals of such an index will give other interested folks in the community a chance to improve the proposal by sharing other perspectives. It might also be interesting to present it as part of a general discussion of navigation — for example, in the early days of writing TSPL, we considered including a glossary of new terms (you can see special newTerm markup in the old RST files), but that wasn't ever built out. What are the different kinds of navigation we can provide to help readers find a topic in the book, and which ones will be the most useful?
