One thing that pleasantly surprised me about Rust was the included offline documentation.
You just run "rustup doc" in terminal & you get all of the Rust book, stdlib docs etc.
Of course on MacOS it's not a problem - you get that & more bundled with Xcode
Is there anything like "swift doc" for Linux? (And potentially for Windows, once it's fully supported)
Online docs are great, but there are situations when internet connection just isn't available (on a plane etc.)
P.S.: yes, I know you can download the Swift book from Swift.org, but what about stdlib & Foundation docs?
Right now there isn't, but I think this would be really great to have in the future! I did a little bit of exploratory work on how best to ship docs along with a compiler toolchain a while back in the context of documenting error messages. I think standard library docs & maybe the API design guidelines would be a natural inclusion if we introduced swift doc or similar.
The book and Foundation docs are a little trickier. The book isn't open source, but it is available under a Creative Commons (CC BY 4.0) license so I think it could be redistributed with attribution. As far as I'm aware, there's no legal way to redistribute the Foundation docs.
Not all of Darwin Foundation is in the open-source project. The Foundation documents being referenced are part of the Apple documentation for Darwin Foundation, which is the reason for the uncertainty about re-distribution. It is available on the web, for what that's worth.
The opensource corelibs-foundation implementation is documented. It is a matter of generating the docs. There is the third-party tool Jazzy written in Ruby. Jazzy tries to mimic the official Apple documentation and to be honest i don't really like that design. It worked better for a language like Objective-C whereas Swift has a very advanced type system. A documentation generator written in and distributed with Swift would be great.
The inline docs for corelibs-foundation (example) are in the source repository, which means they are available under the same license as the code. Apple distributes their own version of Foundation (as well as the Swift compiler) as part of their own SDK.
This actually raises an important point - very large parts of the open-source version of Foundation are entirely undocumented (e.g. DateFormatter, Bundle, etc), while the Apple equivalents have comprehensive documentation (e.g DateFormatter, Bundle). It's a bit hit-and-miss, though: some types like Date and URL are pretty well documented in the OSS version, too (but even then, sometimes the documentation contains artefacts from Obj-C, like this part which warns against passing nil for a non-optional argument).
This all makes me think the current, poor documentation in corelibs-foundation is more of an oversight than a licensing/copyright issue. @millenomi or @Tony_Parker will likely know.
I think the issue is not that documentation doesn't exist for corelibs-foundation, but, that one has to download the source distribution to get it, in addition to it's incomplete nature. The only place I've been able to find documentation about Foundation libraries (including pieces not included in the open source project) without having to download the source is Apple. Xcode is the only place that has complete documentation and is available off-line. The distribution rights to that documentation is uncertain.
If there are other places where the documentation can be downloaded without requiring the source code, I would like to know.
If the entire documentation was in-line, it could be distributed with the library as it is with many Swift packages (including the standard library). Xcode uses a code-like view for that, but other tools could present the information in other ways.
I'd love to see the in-line documentation made available in the REPL. I spend a lot of time working in the REPL and while it's not hard to switch to a browser or Xcode to read docs, it would be super convenient to be able to pull up the docs in place like with a man page. Would also be cool to have parameter descriptions display underneath the command line on tab complete.
The only place that I can find polished documentation about stdlib, Foundation (corelibs and otherwise), is in the Apple documentation. Swift.org actually points me at the Apple Developer pages from their page. I understand the source code is documented but, it doesn't seem to have the polish that is shown in the Apple documentation, or in the Swift Language Reference e-book, and it's not organized except on a file-by-file basis. At least, I couldn't find anything like .html files, Markdown files or ReST files that contained the information that is in the Apple Developer pages outside of the comments in the source code files. And, the Apple documentation is included in the Xcode installation (albeit, hard to find). If you are looking for that level of documentation for off-line use, it seems like Apple is the only source right now, and its stance on re-distributing the Xcode documentation is uncertain at best.
And, if an organization were to develop that level of documentation based off the source code comments, augmented to the level desired, it's still not clear what it's re-distribution rights would be, as a total package.
Who should generate that that level of documentation and how it gets generated, if it does not exist outside of Apple, is a separate issue.
swiftdoc.org is an example of what a good-looking UI to the code-level documentation could look like. Personally, I think it's the best documentation around, even though it hasn't been updated in a while (@mattt) and doesn't include Foundation.
To be incredibly clear, the documentation for Foundation on developer.apple.com is meant to apply to all versions, modulo the deprecations and obsoletions in SCF. Discrepancies are generally bugs.
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.
Is there any work currently being done on some kind of offline-doc generator like the mentioned Jazzy but in Swift? (presumably using the inline documentation from stdlib, foundation etc.)
If so, I'd like to help at least a bit.
SwiftDoc.org seems cool, but I understand it's online only and not updated for Swift 5 & 5.1
I'm happy to report that SwiftDoc.org is now updated for Swift 5.1.
This most recent update is powered by swift-doc, which aims to do pretty much exactly what you're describing. (See the "Motivation" section for some background for why it took so long to get SwiftDoc.org updated)
I don’t see the “view protocol hierarchy” links though. That was one of the most powerful features on swiftdoc.org for understanding type relationships. Is it on the roadmap to add it back?
For reference, here is what the hierarchy looked like on Array in Swift 4.2.
Edit: for some reason the embedded links in the hierarchy don’t work for me there. Here’s a direct link to the svg for Array where all the types in it are clickable.
And just for good measure, here’s the same thing for FloatingPoint, which I think better illustrates the power of these graphs. I’d really like to see them available for the current version of Swift.
