You can use the resources on this page as documentation for the Swift language.Apple hosts additional resources for learning Swift—such as videos, sample code and playgrounds, and additional documentation—including the Swift standard library reference.
Xcode’s Quick Help, Documentation and API Docs. Xcode includes documentation, and documentation tools, right within the IDE. We’ve already seen the Quick Help Inspector in this tutorial, but there’s more! Documentation about your code, such as quick help annotations and code comments. Xcode includes everything developers need to create great applications for Mac, iPhone, iPad, Apple TV, and Apple Watch. Xcode provides developers a unified workflow for user interface design, coding, testing, and debugging. The Xcode IDE combined with the Swift programming language make developing. Xcode 11.4 changed the way frameworks are linked and embedded, and you may see the following errors when switching between iOS devices and simulators: Building for iOS, but the linked and embedded framework 'App.framework' was built for iOS Simulator.
Code signing identity to use for signing. It can be created with Xcode and added to your keychain. Starting with Xcode 8 you should use -codeSignIdentity='iPhone Developer' both for debug and release. Development Team-developmentTeam: The development team to use for code signing. You would use this setting and a simplified Code Sign Identity (i.e. Just 'iPhone Developer') to sign your apps, you do.
The Swift Programming Language
The Swift Programming Language is the authoritative reference for Swift,offering a guided tour, a comprehensive guide, and a formal reference of the language.You can read the book here:
How To Use Xcode
- The Swift Programming Language
You can also download the latest version as an ePub, available under a Creative Commons Attribution 4.0 International (CC BY 4.0) License.
Apple Xcode Guide
Translations
We encourage you to participate in translating The Swift Programming Language into other languages. Get involved with an existing translation project, or start a new one where there’s a need. For example:
Chinese translationand its GitHub project
Korean translationand its GitHub project
If you know of a quality translation project underway, please let us know on the Compiler Development forums,and we’ll do our best to provide a link to that project from this page.
Swift Package Manager
The Swift Package Manager is a tool for managing the distribution of Swift code.It’s integrated with the Swift build system to automate the process ofdownloading, compiling, and linking dependencies. The package manager manifestAPI documentation is available here.
API Design Guidelines
A goal for Swift is for code to share a uniform standard for the programmer’suser experience, much of which is defined by the names and idioms that appearin APIs. These design guidelines explain how tomake sure that your code feels like a part of the larger Swift ecosystem.
Migration Guides
Xcode includes a Swift Migrator tool that helps you migrate your project to the latest version of Swift, or update it to work with the latest SDKs.
Code structure and organization is a matter of pride for developers. Clear and consistent code signifies clear and consistent thought. Even though the compiler lacks a discerning palate when it comes to naming, whitespace, or documentation, it makes all the difference for human collaborators.
This week, we’ll be documenting the here and now of documentation in Swift.
Since the early ’00s, Headerdoc has been Apple’s preferred documentation standard. Starting off as little more than a Perl script that parsed trumped-up Javadoc comments, Headerdoc would eventually be the engine behind Apple’s developer documentation online and in Xcode.
But like so much of the Apple developer ecosystem, Swift changed everything. In the spirit of “Out with the old, in with the new”, Xcode 7 traded Headerdoc for fan favorite Markdown — specifically, Swift-flavored Markdown.
Documentation Comments & Swift-Flavored Markdown
Even if you’ve never written a line of Markdown before, you can get up to speed in just a few minutes. Here’s pretty much everything you need to know:
Basic Markup
Documentation comments look like normal comments, but with a little something extra. Single-line documentation comments have three slashes (///). Multi-line documentation comments have an extra star in their opening delimiter (/** ... */).
Standard Markdown rules apply inside documentation comments:
- Paragraphs are separated by blank lines.
- Unordered lists are marked by bullet characters (
-,+,*, or•). - Ordered lists use numerals (1, 2, 3, …) followed by either a period (
1.) or a right parenthesis (1)). - Headers are preceded by
#signs or underlined with=or-. - Both links and images work, with web-based images pulled down and displayed directly in Xcode.
Summary & Description
The leading paragraph of a documentation comment becomes the documentation Summary. Any additional content is grouped together into the Discussion section.
If a documentation comment starts with anything other than a paragraph, all of its content is put into the Discussion.
Parameters & Return Values
Xcode recognizes a few special fields and makes them separate from a symbol’s description. The parameters, return value, and throws sections are broken out in the Quick Help popover and inspector when styled as a bulleted item followed by a colon (:).
- Parameters: Start the line with
Parameter <param name>:and the description of the parameter. - Return values: Start the line with
Returns:and information about the return value. - Thrown errors: Start the line with
Throws:and a description of the errors that can be thrown. Since Swift doesn’t type-check thrown errors beyondErrorconformance, it’s especially important to document errors properly.
Are you documenting a function whose method signature has more arguments than a Hacker News thread about tabs vs. spaces? Break out your parameters into a bulleted list underneath a Parameters: callout:
Additional Fields
In addition to Parameters, Throws and Returns, Swift-flavored Markdown defines a handful of other fields, which can be loosely organized in the following way:
- Algorithm/Safety Information
PreconditionPostconditionRequiresInvariantComplexityImportantWarning- Metadata
AuthorAuthorsCopyrightDateSeeAlsoSinceVersion- General Notes & Exhortations
AttentionBugExperimentNoteRemarkToDo
Each of these fields is rendered in Quick Help as a bold header followed by a block of text:
Field Header:
The text of the subfield is displayed starting on the next line.
Code blocks
Demonstrate the proper usage or implementation details of a function by embedding code blocks. Inset code blocks by at least four spaces:
Fenced code blocks are also recognized, delimited by either three backticks (`) or tildes (~):
Documentation Is My New Bicycle
How does this look when applied to an entire class? Quite nice, actually!
Option-click on the initializer declaration, and the description renders beautifully with a bulleted list:
Open Quick Documentation for the method travel, and the parameter is parsed out into a separate field, as expected:
MARK / TODO / FIXME
In Objective-C, the preprocessor directive #pragma mark is used to divide functionality into meaningful, easy-to-navigate sections. In Swift, the same can be accomplished with the comment // MARK:.
The following comments are surfaced in the Xcode source navigator:
// MARK:// TODO:// FIXME:
Other conventional comment tags, such as NOTE and XXX aren’t recognized by Xcode.
As with #pragma, marks followed by a single dash (-) are preceded with a horizontal divider
To show these new tags in action, here’s how the Bicycle class could be extended to adopt the CustomStringConvertible protocol, and implement the description property.
Bringing everything together in code:
At the time of writing, there’s no official tool for transforming documentation comments into something more tangible than Quick Help panels in Xcode,
Fortunately, where necessity arises, open source (often) delivers.
Jazzy
Jazzy is a terrific open-source command-line utility that transforms your project’s documentation comments into a set of Apple-like HTML documentation (but that nice vintage style, before that whole redesign). Jazzy uses Xcode’s SourceKitService to read your beautifully written type and method descriptions.
Install Jazzy as a gem, then run from the root of your project folder to generate documentation.
Take a peek at a Jazzy-generated documentation for the Bicycle class.
Although the tooling and documentation around Swift is still developing, one would be wise to adopt good habits early, by using the new Markdown capabilities for documentation, as well as MARK: comments in Swift code going forward.
Go ahead and add it to your TODO: list.