swiftlang / swift-book Goto Github PK
View Code? Open in Web Editor NEWThe Swift Programming Language book
License: Apache License 2.0
The Swift Programming Language book
License: Apache License 2.0
No response
This code type checks and infers T: Hashable
:
func foo<T>(_: Set<T>) {}
A more complex example; we infer T.Element: Hashable
:
func foo<T: Sequence>(_: T) -> Set<Array<T.Element>> {}
I couldn't find mention of this behavior anywhere in TSPL.
No response
No response
I think we should fix them and consider adding the --warning-as-error flag to the PR's CI workflow when the such ability is implemented.
https://forums.swift.org/t/add-support-for-warnings-as-errors/59832/5
@Comment
?(about 2/3 of warnings are caused by this) cc @franklinschEnv: Xcode 14.0 beta 6 with its bundled default Swift toolchain
Chapter "Opaque Types"
Section "Differences Between Opaque Types and Protocol Types”
The section says that the protoFlip(_:)
function, which accepts types that conforms to the Shape
protocol defined earlier in this chapter, does not nest. And code lie protoFlip(protoFlip(smallTriange))
is invalid. While it successfully compiles and works, that is contrary to the text written in this section.
The code:
import Foundation
protocol Shape {
func draw() -> String
}
struct Triangle: Shape {
var size: Int
func draw() -> String {
var result: [String] = []
for length in 1...size {
result.append(String(repeating: "*", count: length))
}
return result.joined(separator: "\n")
}
}
struct FlippedShape<T: Shape>: Shape {
var shape: T
func draw() -> String {
let lines = shape.draw().split(separator: "\n")
return lines.reversed().joined(separator: "\n")
}
}
struct Square: Shape {
var size: Int
func draw() -> String {
let line = String(repeating: "*", count: size)
let result = Array<String>(repeating: line, count: size)
return result.joined(separator: "\n")
}
}
struct Rect: Shape {
var width: Int
var height: Int
func draw() -> String {
let line = String(repeating: "*", count: width)
let result = Array<String>(repeating: line, count: height)
return result.joined(separator: "\n")
}
}
func protoFlip<T: Shape>(_ shape: T) -> Shape {
if shape is Square {
return shape
}
return FlippedShape(shape: shape)
}
let smallTriangle = Triangle(size: 3)
let protoFlippedTriangle = protoFlip(protoFlip(protoFlip(smallTriangle))) // This code is invalid according to the text in section
print(protoFlippedTriangle.draw())
Output:
***
**
*
I think it is better to rewrite the example with a protocol that defines the requirement of the associated type.
https://docs.swift.org/swift-book/ReferenceManual/Declarations.html#ID374
For example, P2
in the following code:
protocol P1 {
associatedtype T
}
protocol P2 {
associatedtype T: Comparable = Int
}
// P2 is equivalent to
protocol P3 where T: Comparable {
associatedtype T = Int
}
The reference section "Protocol Associated Type Declaration" doesn't discuss this feature, nor does the guide, and there aren't any examples showing it. Adding it to the reference first would follow our general approach.
The current grammar produces all three examples above. The rule for protocol-associated-type-declaration
produces type-inheritance-clause
followed by typealias-assignment
, which allows the : Comparable and = Int
from above.
rdar://31876806
https://docs.swift.org/swift-book/LanguageGuide/AdvancedOperators.html
https://docs.swift.org/swift-book/LanguageGuide/AdvancedOperators.html has this:
For information about the operators provided by the Swift standard library, including a complete list of the operator precedence groups and associativity settings, see Operator Declarations.
links to apple page. I believe it should be linked to a page hosted on docs.swift.org.
No response
Previous ID | SR-8761 |
Radar | None |
Original Reporter | @natecook1000 |
Type | Improvement |
Votes | 0 |
Component/s | |
Labels | Improvement |
Assignee | None |
Priority | Medium |
md5: 5483446fdf4d37083296d04e708f33f2
Issue Description:
We don't appear to document the way you can provide a default type in an associate's type declaration. Noted in https://forums.swift.org/t/a-question-about-associatedtype-in-protocols/16168
The book's style guide lists the underlines for ReStructured Text headings.
However, the book uses #
-prefixed ATX headings.
Right now, the grammar in Language Reference is implemented using plain code listings. The shipping book includes a custom presentation for the grammar, including cross-references between different grammar elements and a page that hosts the generated summary of the grammar.
rdar://101001280
The version of TSPL currently published using the pre-DocC toolchain styles each item in the definition of a grammar rule as a link to that item's own definition. The live link makes it easy to follow a series of production rules, one step at a time.
DocC doesn't currently have the ability to link to somewhere on the page other than a heading.
Is it possible to downgrade to 5.6 to make it usable for mere mortals that run latest Monterey?
Previous ID | SR-12942 |
Radar | None |
Original Reporter | erickpc (JIRA User) |
Type | Bug |
Attachment: Download
Votes | 0 |
Component/s | |
Labels | Bug, Documentation |
Assignee | None |
Priority | Medium |
md5: 40885081a51d49565b9dd89413fc2e4b
Issue Description:
The documentation here https://docs.swift.org/swift-book/ReferenceManual/Declarations.html#ID545 states:
In-out parameters are passed as follows:
When the function is called, the value of the argument is copied.
In the body of the function, the copy is modified.
When the function returns, the copy’s value is assigned to the original argument.
By reading that, if any changes are made to the argument outside of the function between. step 1 and 3, those changes would be lost when the function returns. The scenario I'm describing would be:
Pass array a `[1, 2, 3]` as an In-Out argument to function `f()`
While `f()` is executing, outside the function, `a` gets modified to add another value.
At this point `a` is `[1, 2, 3, 4]`
When `f()` finishes executing the copy of `a` copied back to the calling context, losing the last value 4.
That's the expected behavior according to the documentation. I have this test case showing it doesn't work that way. Down below the documentation mentions an "optimization" that "satisfies all of the requirements of the copy-in copy-out model while removing the overhead of copying." That last part is misleading. This "optimization" explains the behavior I'm seeing, but if I were to "Write your code using the model given by copy-in copy-out, without depending on the call-by-reference optimization" I would be surprised the system is not working as expected.
Attached is the test case
PS: The double quotes above are to show what's in the documentation verbatim.
Expression patterns appear only in switch statement case labels.
This is not true. Expression patterns may appear in both switch
case items and case conditions. For example, if case 0 = i {}
or while case .function(let name, numParams: 0) = node {}
.
rdar://46341816
Currently the content contains a lot of manual line breaks.
Take a look at the rendered first paragraph of the current website:
And now take a look at the content source:
Swift is a new programming language for iOS, macOS, watchOS, and tvOS app development.
Nonetheless, many parts of Swift will be familiar
from your experience of developing in C and Objective-C.
Or more clear by looking at it in Xcode, where line numbers are written our:
Having to think about inserting line breaks manually to make it render nicely is cumbersome. It breaks flow when typing and surely it is a presentation matter? Also, it prevents dynamic width of the rendered book!
I suggest we rid the book of these manual line breaks and allow large screens to make use of its pixels!
To summarise, my suggestion has two advantages:
In the following portion of the grammar:
> Grammar of an identifier:
>
> *identifier* → *identifier-head* *identifier-characters*_?_
>
> *identifier* → **`` ` ``** *identifier-head* *identifier-characters*_?_ **`` ` ``**
The CommonMark definition of a code voice permits one or more backticks, which supports exactly this sort of scenario where a backtick needs to appear in code voice. Additionally, escaping via backslash isn't allowed in code voice.
The issue here is a collision with DocC's extended markup using double-backticks surround links to API symbols. Currently, building with top-of-tree docc
, the output is correct but we get warnings like the following:
Topic reference '`' couldn't be resolved. No local documentation matches this reference.
https://docs.swift.org/swift-book/ReferenceManual/Expressions.html#ID563
referenced from
https://developer.apple.com/documentation/swift/keypath
The link functions, but redirects to the top of the overall TSPL, and it's not clear how to get to the relevant information. I'm not sure you can even just to the subheading within Expressions in the reference manual, but it would help to at least redirect to Expressions in the reference section, if that's possible.
Ideally the link should direct to the subheading in Expressions: https://docs.swift.org/swift-book/documentation/the-swift-programming-language/expressions#Key-Path-Expression
Currently, the formal grammar is manually duplicated — each rule appears one in its section reference, and again in the summary of the grammar at the end of the reference. This would be improved by some form of automation.
A simple improvement would be to script the process of collecting the grammar, so we could run that script and generate a new Summary of the Grammar chapter after any updates to the grammar. It would be even better to run that script as part of building the book, or when the grammar changes, or to have some automated reminder that the summary has become outdated.
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.
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.
Update Language Guide in time just like Rust Book.
Or maintain a cheat sheet.
In the document, the Chapter "Opaque Types" describes the difference between protocol types and opaque types as function return types as follows:
Another problem with this approach is that the shape transformations don’t nest. The result of flipping a triangle is a value of type
Shape
, and theprotoFlip(_:)
function takes an argument of some type that conforms to theShape
protocol. However, a value of a protocol type doesn’t conform to that protocol; the value returned byprotoFlip(_:)
doesn’t conform toShape
. This means code likeprotoFlip(protoFlip(smallTriangle))
that applies multiple transformations is invalid because the flipped shape isn’t a valid argument toprotoFlip(_:)
.
However, in practice, unlikely, it is valid as proven by the following example:
#if swift(>=5.8)
print("hello swift 5.8+")
#endif
protocol Shape {
func draw() -> String
}
struct Triangle: Shape {
var size: Int
func draw() -> String {
var result: [String] = []
for length in 1...size {
result.append(String(repeating: "*", count: length))
}
return result.joined(separator: "\n")
}
}
struct FlippedShape<T: Shape>: Shape {
var shape: T
func draw() -> String {
if shape is Square {
return shape.draw()
}
let lines = shape.draw().split(separator: "\n")
return lines.reversed().joined(separator: "\n")
}
}
struct Square: Shape {
var size: Int
func draw() -> String {
let line = String(repeating: "*", count: size)
let result = Array<String>(repeating: line, count: size)
return result.joined(separator: "\n")
}
}
func flip<T: Shape>(_ shape: T) -> some Shape {
return FlippedShape(shape: shape)
}
func protoFlip<T: Shape>(_ shape: T) -> Shape {
if shape is Square {
return shape
}
return FlippedShape(shape: shape)
}
let smallTriangle = Triangle(size: 3)
let nestedThing = protoFlip(protoFlip(smallTriangle))
print(nestedThing.draw())
// hello swift 5.8+
// *
// **
// ***
Discussion in here: https://forums.swift.org/t/nesting-functions-returning-protocol-types-arent-invalid-in-swift-5-8/64366
The following phrase sounds confusing:
"However, a value of a protocol type doesn’t conform to that protocol."
And it should prompt a compile error.
The shipping book supports an offline reading experience with an ePUB version available on swift.org and on Apple Books. We should evaluate which formats we want to support going forward, and where in the publication pipeline we generate these artifacts.
Blocked by: swiftlang/swift-docc#354
rdar://71373710
The page in the docs where it appears:
https://docs.swift.org/swift-book/documentation/the-swift-programming-language/automaticreferencecounting#Unowned-Optional-References
The actual files in the repository:
https://github.com/apple/swift-book/blob/main/TSPL.docc/Assets/[email protected]
https://github.com/apple/swift-book/blob/main/TSPL.docc/Assets/[email protected]
The 3rd course is named "p" in the diagram, which doesn't match the example code above it.
The 3rd course should be named "Caring for Tropical Plants".
rdar://109160486
The book's chapters are divided into three parts: the Guided Tour, Language Guide, and Language Reference. As a result, the automatically generated See Also sections at the end of each chapter are fairly distracting (and obviated somewhat by DocC's new sidebar). We should consider adopting some proposed DocC improvements like @AutomaticSeeAlso(disabled)
and @AutomaticPagination
.
rdar://101885438
Description
A class extension that is declared as private automatically turns all methods and types declared in the extension as private. This gets rid of the need to explicitly declare each method and type declared in the extension as private. However, if a type (say, an enum) declared in the extension is explicitly declared as private (which would be unnecessary but seems to be legal), and if one of the methods in the extension takes this enum as a parameter, then the compiler requires that the method be explicitly declared as private as well.
Steps to reproduce
class Foo {}
private extension Foo { // The extension is declared as private, so everything in it will be private as well
private enum Bar { // This is unnecessarily declared as private, but it seems like a legal move
case FirstCase
}
// The following method takes as a parameter a type that is explicitly declared as private
func testFunction(case: Bar) {} // The compiler complains that this method should be declared as private, when it is already private in virtue of being inside an extension that is declared as private
}
The compiler stops complaining if the enum Bar
isn't explicitly declared as private anymore. However, whether the enum Bar
is explicitly declared as private or not, it will be private by virtue of being inside a private extension.
Is this a bug? To me it seems so, but if others have different opinions I'd like to hear them as well.
Environment
Previous ID | SR-14465 |
Radar | rdar://problem/76466123 |
Original Reporter | amos (JIRA User) |
Type | Bug |
Any web browser
Votes | 0 |
Component/s | |
Labels | Bug, Documentation |
Assignee | None |
Priority | Medium |
md5: 636d25b780d6f98d27615d54de6badbd
Issue Description:
Many images in the language guide on docs.swift.org are missing meaningful alt text. Please fix so people using screen readers can fully experience the docs.
For example: in the strings and characters section, the image illustrating handling of indentation in multi-line strings has the image path as its alt text.
The second to last paragraph of the Version Compatibility page of the Swift book incorrectly states concurrency requires '5.7 or later'. It should state '5.5 or later'. (My guess is someone did a 'replace all'.)
The same paragraph also says to, "set a deployment target of at least iOS 15, macOS 12, tvOS 15, or watchOS 8.0" which was correct at the time Swift 5.5 was released, but since Xcode 13.2 it is possible to use Swift Concurrency (but not all the new APIs) back to "macOS Catalina 10.15, iOS 13, tvOS 13, and watchOS 6".
Steps to reproduce the behavior:
State facts.
State mix of old facts and new find-and-replace error.
N/A
Swift 5.7 book (that is all I could find)
N/A
To facilitate contributions, I recommend adding a "Make a contribution" banner or button to the header or footer of each page. This will allow users to easily submit pull requests if they notice any errors on that particular page. Clicking the banner/button will take them directly to the source file for that page with edit mode enabled.
For instance, if a user clicks on the "Make a contribution" banner while viewing the-swift-programming-language/aboutswift, they will be redirected to https://github.com/apple/swift-book/edit/main/TSPL.docc/GuidedTour/AboutSwift.md.
Github's Open Source Doc Workflow
Some parts of the book were written before Swift style standardized on 4 space indentation, and instead uses 3 space indentation. Under the legacy Sphinx-based publication pipeline, this wasn't an issue: code listings are syntax highlighted and reindented using SourceKit as part of publication, producing published output with 4 space indents. DocC preserves indentation, so we need to clean these up in source.
rdar://96988058
In the link above, you can find a sentence that explains extracting associated values through switch statements in the section "Associated Values" in the chapter "Enumerations" as follow:
If all of the associated values for an enumeration case are extracted as constants, or if all are extracted as variables, you can place a single
var
orlet
annotation before the case name, for brevity:
This sentence is confusing, because it sounds like we can use var
annotation for constants as var
comes first before let
.
It is certain to infer the real meaning that var
cannot be used for constants if you were reading through the document from the beginning.
However, it would be better to be written in the correct order for people visiting the section straightforwardly.
If all of the associated values for an enumeration case are extracted as constants, or if all are extracted as variables, you can place a single
let
orvar
annotation before the case name, for brevity:
No response
Currently, DocC doesn't render hard breaks: swiftlang/swift-docc#477
When support is added, we should change the formal grammar here to use blank lines between groups and hard breaks between definitions.
Currently, as a workaround to preserve this information, each definition is followed by a blank line in source, to make it appear on its own line in output, and groups are separated by two blank lines. So something like this:
> Grammar of a self expression:
>
> *self-expression* → **`self`** | *self-method-expression* | *self-subscript-expression* | *self-initializer-expression*
>
>
>
> *self-method-expression* → **`self`** **`.`** *identifier*
>
> *self-subscript-expression* → **`self`** **`[`** *function-call-argument-list* **`]`**
>
> *self-initializer-expression* → **`self`** **`.`** **`init`**
Should turn into something like this:
> Grammar of a self expression:
>
> *self-expression* → **`self`** | *self-method-expression* | *self-subscript-expression* | *self-initializer-expression*
>
> *self-method-expression* → **`self`** **`.`** *identifier* \
> *self-subscript-expression* → **`self`** **`[`** *function-call-argument-list* **`]`** \
> *self-initializer-expression* → **`self`** **`.`** **`init`**
No response
Previous ID | SR-15597 |
Radar | None |
Original Reporter | Saurabh Pote (JIRA User) |
Type | Bug |
Attachment: Download
Playground - Xcode 13.1
Votes | 0 |
Component/s | swift |
Labels | Bug |
Assignee | None |
Priority | Medium |
md5: 3ddc3cc79f130a6791d115057efa79a2
Issue Description:
The swift documentation states that for a private class, a method without an access control specifier will be implicitly a private method(Snapshot1_SwiftDoc) attached. However when the same is executed in a playground, the method is accessible from outside the class(Snapshot2_Playground attached). If we explicitly mark the method as private, then an error is thrown as per Snapshot3_Playground.
I am looking at the list under Keywords and Punctuation. I think await is missing from this list:
Keywords used in expressions and types: Any, as, catch, false, is, nil, rethrows, self, Self, super, throw, throws, true, and try.
Both try and await appear in similar places the grammar, so I think this is an error in the documentation.
Sandor Brecsok
The shipping version of A Swift Tour is available as HTML or ePUB like the rest of the book, but also as a downloadable playground to open in Xcode. The code listings were tailored to take advantage of this interactive format, suggesting changes that the reader can make to each code listing to try out parts of the language.
We should extend DocC and adopt that in TSPL, to support some interactive documentation format like a playground. Or in the interim, we could consider reframing the tour to suggest that readers copy/paste each code listing into a playground or REPL, to see the code running and to edit the code.
rdar://71373440
Some weeks ago I posted a comment on a discussion re. documentation navigation over on the language repo. swiftlang/swift-org-website#24 (comment) and I was encouraged to repost it over here.
To summarise my original comment, the book needs to have a keyword index page which provides links to both the language discussion and grammar sections, and also bi-directional links between grammar and discussion not just for concepts. Currently, finding information on a specific keyword is a long-winded process of trial and error, and relies on a reader having a rough idea as to which category in the book a particular keyword belongs. As I commented in the link re. looking up the then unfamiliar-to-me some
keyword:
The best I could do in the online version is to look in the grammar summary and CMD-F to search on the page, then follow the link to the Type reference, then lookup opaque types in the language guide for the discussion. Quite the journey.
The keyword list in the Lexical Structure is a start, but needs to be expanded to provide linking, and preferably presented in its own book section.
Since then the DocC version of the book has been recently released, and in my opinion there are now some issues related to everyday usage and navigation of the book in this new form. I understand some of these may be caused by deficiencies in DocC, but if that was the case, then the old and new versions should be available in parallel until properly provisioned. While it functions well as a text one might read cover to cover, it's now impossible to navigate around to find things, as highlighted above.
The search facility now does nothing more than return the headings as presented in the contents sidebar, ditto the 'Filter' function at the bottom of the sidebar. I can read the sidebar quicker than I can type a filter.
There now appears to be no reference at all to the PDF and ePub versions of the book on the documentation website (though ePub still available via Apple Books, but not every dev is an Apple hardware user...). I have current copies, and I can at least search in them, albeit with not as fine grained control as a keyword index gives.
Previous ID | SR-896 |
Radar | None |
Original Reporter | douglashill (JIRA User) |
Type | Improvement |
Votes | 1 |
Component/s | Standard Library |
Labels | Improvement, Documentation |
Assignee | None |
Priority | Medium |
md5: fccac19dc8668e07b859568b36ae3644
Issue Description:
Reading through the Swift book in iBooks, the ~= is mentioned but not named. There are numerous advantages to having a clear name:
I am sorry if I am missing the name somewhere; it's hard to search for.
https://docs.swift.org/swift-book/documentation/the-swift-programming-language/patterns
As part of releasing the commit history of the book, we redacted the names of some previous contributors to preserve their privacy. If we redacted your name and you would like acknowledgement, please comment on this issue and include the account info you want to use for attribution.
Describe the bug
Hi, I am currently learning Swift programming language.
Optional Protocol Requirements section in the official Swift programming language document(Swift 5.7) states
Note that @objc protocols can be adopted only by classes that inherit from Objective-C classes or other @objc classes. They can’t be adopted by structures or enumerations.
and provides an example code.
@objc protocol CounterDataSource {
@objc optional func increment(forCount count: Int) -> Int
@objc optional var fixedIncrement: Int { get }
}
// ...
class ThreeSource: NSObject, CounterDataSource {
let fixedIncrement = 3
}
Xcode, however, readily accepts the following code snippet which does not inherit NSObject, and compiles without any problem.
class ThreeSource: /*NSObject,*/ CounterDataSource {
let fixedIncrement = 3
}
Then, am I to understand that the document's description on the limitation is about why optional protocol is introduced to the language in the first place, and not about what is actually enforced by the compiler?
Environment (please fill out the following information)
The attachment contains a list of minor issues in The Swift Programming Language (Swift 5.7) document. The edition reviewed is the ePub download from swift.org, not the online version. These issues are identified for possible resolution in the release of this document for a subsequent version of Swift.
SPL 5.7 Issues.docx
rdar://105507343
When introducing new syntax for the first time, the book uses placeholder literals to show the customizable portion(s) of the syntax being introduced. Right now, these render as regular Swift code blocks that don't have a special treatment for placeholders.
rdar://64038462
When building the book, DocC understands the first paragraph of each chapter to be an abstract for that chapter, which it renders differently from the chapter's content. For example, in navigation you see both the name of the chapter and the abstract.
The current content doesn't include abstracts, so the first paragraph of the actual content is being (incorrectly) treated as an abstract. We should go through each chapter and add abstracts at the beginning. To follow editorial guidelines, the abstract needs to be a single sentence that starts with an imperative verb.
rdar://96321054
The shipping book uses a custom syntax for its tests; we preserved these as DocC comments in the Markdown source, but use regular Swift code blocks to render them without running and testing the code as part of the build process. We should evaluate how to bring these tests back, potentially using Swift Snippets.
After #1, #36 and swiftlang/swift-docc#377 were resolved, currently there should be no warnings when building the newest swift-book using the newest swift-docc.
Input:
/Users/kyle/Workspace/Github/swift-docc-project/swift-book/Sources/TSPL/TSPL.docc
Template:
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault
.xctoolchain/usr/bin/../share/docc/render
==============================
Starting Local Preview Server
Address: http://localhost:8080/
==============================
Monitoring
/Users/kyle/Workspace/Github/swift-docc-project/swift-book/Sources/TSPL/TSPL.docc
Maybe we should consider to config a CI check to make sure a future PR will not produce any new warning or error(with --warnings-as-errors
enabled on swift-docc side).
https://forums.swift.org/t/add-support-for-warnings-as-errors/59832/5
Per discussion in the docs workgroup, it'd be good to have a preview version of the DocC output that we can all look at as we work toward publishing the book on swift.org. This preview should be:
rdar://101885227
As we get ready to publish the DocC version of, we’re taking a review pass over the entire book, to check for markup issues, DocC bugs, or problems with the RST-to-markdown conversion. This issue tracks which chapters have been reviewed.
Welcome to Swift:
Language Guide:
Language Reference:
Revision History:
Previous ID | SR-14030 |
Radar | rdar://problem/73014172 |
Original Reporter | @woolsweater |
Type | Bug |
Swift Book v5.3 on swift.org
Votes | 0 |
Component/s | |
Labels | Bug, Documentation |
Assignee | None |
Priority | Medium |
md5: f52f6b8e5201224bbb536e153db0c38b
Issue Description:
The grammar rule for "interpolated-text-item" specifies a single expression inside parentheses:
interpolated-text-item →
\ (
expression)
| quoted-text-item
but Swift actually accepts the equivalent of a tuple expression after the backslash, something like:
interpolated-text-item →
\ (
interpolated-text-list)
| quoted-text-item
interpolated-text-list → interpolated-text-element | interpolated-text-element,
interpolated-text-list
interpolated-text-element → expression | identifier:
expression
In some places, TSPL links to a H4 as an anchor point — for example:
// In Statements.md
#### Switching Over Future Enumeration Cases
// In Attributes.md and RevisionHistory.md
<doc:Statements#Switching-Over-Future-Enumeration-Cases>
However, swift-docc currently only supports H1, H2 and H3 as an anchor to reference.
Should we update the structure of content in this repo or should this be a feature/bug on swift-docc to be fixed?
If we are going to fix it on swift-docc, should we add a flag to let the consumer decide which heading level we should add as anchor or just extend it to level 4?
Because of the way Swift-DocC works, the URL we publish to must change from https://docs.swift.org/swift-book to https://docs.swift.org/documentation/swift-book. We need to set up server-side redirects on Swift.org so that links to chapters continue to work. These should be relatively straightforward.
In addition, TSPL specifies a stable ID for each heading's anchor. This is used for on-page navigation within the book, and frequently used outside of the book to provide a link directly to a specific heading. Because the DocC dialect of markdown doesn't allow us to specify an anchor's ID, all of these stable IDs will be destabilized and instead derived from the text of the section heading. (See also swiftlang/swift-docc#345)
For the second issue, we don't believe the web server can inspect the URL's fragment and offer different redirect options. It may be possible to use a bit of JavaScript on a "trampoline" page, located at the old URL, to redirect to the new URL.
rdar://96321914
I recently fixed some typos in #11 and since this is a repo for a book, spelling and grammar is extra important (compared to code repo).
Has anyone any experience with Github Actions for Spell Checking, e.g. this: https://github.com/marketplace/actions/check-spelling ?
Description
I would like to point out that in the new format of the Swift Book (on Swift.org), a footer has been inserted which does not allow the dark mode/light mode switch to be seen and used. The mode therefore depends solely on the general setting of the Mac. In my case, this is definitely inconvenient because I can only use Dark Mode which (at least for me) is very annoying.
I don't know if this is the right place for this report, and if not, I apologise.
Steps to reproduce
Expected behavior
Environment
Previous ID | SR-7931 |
Radar | rdar://problem/41028037 |
Original Reporter | @jepers |
Type | Improvement |
Votes | 0 |
Component/s | |
Labels | Improvement |
Assignee | None |
Priority | Medium |
md5: 1cae1d1241f8af82feb6fd18d96e0fef
Issue Description:
Related forum thread.
For example this:
typealias Map = Dictionary
is a short hand form for:
typealias Map<K: Hashable, V> = Dictionary<K, V>
according to this forum post by @slavapestov.
But afaict there doesn't seem to be any mention of this in any documentation.
So I guess it should be documented in eg this section:
https://docs.swift.org/swift-book/ReferenceManual/Declarations.html#ID361
And more generally, a lot of the behavior of type aliases, associated types and extensions is both undocumented and inconsistent/broken.
Properly documenting the intended behavior would certainly help not only us (new and seasoned) users but also the compiler devs.
We don't appear to document the way you can provide a default type in an associate's type declaration. Noted in https://forums.swift.org/t/a-question-about-associatedtype-in-protocols/16168
The grammar of a protocol associated type declaration includes an optional typealias-assignment clause, but doesn't explain what the meaning of that is. An explanation could probably be added to the Associated Types section of the Generics article.
This was originally tracked by #41.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.