Here is the page in question: Attributes — The Swift Programming Language (Swift 5.7)
Could the documentation for Attributes in the Swift 5+ manual be rewritten for careful clarity?
I need to use the different attributes for my Swift for TensorFlow project and cannot parse unless I have this information.
Could you clarify what you find confusing about the documentation there? What would make it better for your needs?
It is not written from first principles. If someone reads the following segment of documentation, they will not understand clearly unless they can ground every single word for the attribute frozen. Thus, it needs to be rewritten for clarity, not for precision in terms of technical terms with code usage examples and definitions for every unclear word.
From the following "documentation": The Swift Programming Language: Redirect
frozen
Apply this attribute to a structure or enumeration declaration to restrict the kinds of changes you can make to the type. This attribute is allowed only when compiling in library evolution mode. Future versions of the library can’t change the declaration by adding, removing, or reordering an enumeration’s cases or a structure’s stored instance properties. These changes are allowed on nonfrozen types, but they break ABI compatibility for frozen types.
What is enumeration mean in this context?
What is library evolution mode in this context?
What is instance properties in this context?
What is nonfrozen?
What is ABI compatibility?
What is frozen types (isn't that a kind of self-definition)?
Everything needs to be hyperlinked with a hover definition like a doxygen documentation.
This is simply unacceptable for such a popular language!
Umm, what is the first principle?
Basically, where there aren't any assumptions made w.r.t. ambiguous and undefined technical keywords and concepts? What is confusing about this? Hyperlinks to the definition and an example for each ambiguous and undefined technical keywords makes the documentation less hand-wavy.
Please check out this Wikipedia article and make the appropriate changes. If you cannot do it, could you send me the link to the source code of the attributes so I can inspect the difficulty of making the attributes well-understood to every capable programmer?
Could you please connect me with the people who are in charge of the documentation at Swift.org? Thanks in advance!
This is not a standalone web page, but, one of several of a extremely well-written book, that has made been available as series of related web pages.
I am a very capable programmer, having spent 50 years in the business, and I have had no problem understanding this page whatsoever.
To the moderator: I'm sorry for the rant, but, it seems to me that we've been seeing more folks "demanding" that circumstances change because the state of being is "completely unacceptable." The tenor of the attitude seems to me to be completely att odds with the aims of these forums.
struct vs. enum as simple as that. Both terms are fully written out in the docs. ;)
Like I said earlier, could you send me the contact email of the documentation writers for Swift.org? I would like to ask more questions about the step-by-step procedure and format that developers or technical writers go through so that the code documentation follows some standard of quality.
By the way, I read as much of the book as I could understand without Google-searching every keyword and piecing together the meaning from the context and Google search results. Thus, that is not very helpful and thus, I would like to contribute myself.
You'll have to talk with @tkremenek(the Swift project manager) about that. As far as I know, the actual editing and publishing is done by Apple, using their corporate technical documentation teams and processes, which they may or may not wish to share. But, I could be wrong.
You might want to have a list of issues with the book you think are missing or incomplete. However, both book and web pages assume a certain familiarity with concepts that originate in C/C++/Objective-C/Objective-C++/clang/LLVM since these are the foundation of Swift.
There are third-party books on Amazon, etc., that you can purchase if you need a more elementary introduction to Swift.
The free Swift 5 book from Apple is what you are talking about, right? Please clarify. I have already gone through tens of Swift books in the past and none mention Attributes in depth. Also, do you know where in the source code they are implemented? I have written many internal apps in Swift/Obj-C so I am am a very capable programmer with 33 years of experience in CS.
Apple e-book, version 5.1, page 1,110 starts the discussion on Attributes. You can to it from the Table of Contents, and from the various descriptions of the language that use attributes. But, it's the same as the Swift.org web page.
Why did you have to spend on Google-searching?
UPDATE: I apologize, I didn't realize that @frozen didn't get discussed in the 5.1 version of the e-book. However, if the whole idea of ABI stability is unclear, you might want to look at the documentation on Github (apple/swift), in the documentation folder. There are several papers that discuss the idea of ABI stability and the changes to the language that were implemented. Note that ABI stability only applies to Darwin; Linux, Windows, et al, are not ABI-stable.
The material is maintained by the technical documentation teams at Apple and contributed for distribution on Swift.org. This is all good feedback, and I have made them aware of this thread. Constructive feedback is always welcome. Please feel free to provide that kind of feedback on this thread.
Hi @tkremenek,
Nothing has changed.
Could the documentation for Attributes in the Swift 5+ manual be rewritten for careful clarity?
I need to use the different attributes for my Swift for TensorFlow project and cannot parse unless I have this information.
Hi,
What happened? No changes in the documentation. Is there any technical documentation teams and processes at Apple? Or there is no funding for that?
Shyamal
Thanks for bringing this up. I suspect this is a case of there are always more things to do than time to do them. The request here was fairly open-ended too.
This book is open source now, and has been since last August. It is in the community’s shared hands to maintain it. That includes Apple, but others too if they want to contribute. If folks see areas they’d like to improve with suggested wording changes, feel free to propose them. The repository is also a good place to file issues.
@shyamalchandra, you should be able to see and file issues for the book here:
I recommend filing your request there.
@tkremenek: No one wants to document it on the swift-book.
I need step-by-step understanding of each macro possible.