The state of Swift documentation

[Karl]

Big +1 to this. Thanks for bringing these issues to everybody's attention.

@ole

The API documentation is Apple-centric

This is a huge issue. Even if you take advantage of everything the toolchain provides (e.g. sourcekit-lsp), the experience on Linux is still really barebones.

Not all software is entirely cross-platform, and you often need to browse the available API as it looks on your system. Xcode has CMD+Click to show generated interfaces, but on Linux there's just nothing. sourcekit-lsp can only handle very basic workflows, and code completion is really not a substitute to having a complete interface in front of you. It just feels unloved - like a hack more than a supported platform.

Even if we have some better web documentation (which is really important), we still need good local tools. I'm aware of the swift-doc project and I'm really hopeful that it'll get us closer to where we need to be.

@ole

Core Libraries have no documentation for non-Apple platforms

This has come up before, and there are a couple of things to note.

The first thing is that Foundation's documentation is just low quality in general. Take a look at the documentation for Date.timeIntervalSince(_:), for example:

1. The parameter is referred to as both another and anotherDate. Both are wrong: the parameter's actual name is just date.
2. The documentation warns us that the result is undefined if the object is nil -- but the parameter isn't an optional type, so it can't be nil.
3. "the receiver" is a bit of an Obj-C anachronism, because of the whole message-based dispatch. It's a minor nit, but I don't think we tend to talk about senders/receivers in Swift.

This isn't limited to Linux. It's just as bad on Darwin platforms:

Interestingly there is apparently another, separate set of documentation (although honestly, it appears to be just as poor in places):

@millenomi

Generally speaking, the documentation on developer.apple.com is not doc-comments in the source (you can see the current Darwin Foundation inline comments in the .h files for that framework.) Those are generally what we'd love to keep in sync, but we haven't made a strong effort yet.

Honestly I think the Foundation team need to seriously rethink their documentation strategy overall. One of the goals should be to improve access and consistency, but they also need to improve quality. Since they don't take community contributions, all we can do is grumble at the poor experience we're forced to tolerate.

@ole

I recently found out that the new XCTIssue API in XCTest is not part of Swift 5.3 on Linux, requiring me to rewrite some code I had just written.

Nobody knows what the evolution process for XCTest is.