Keyboard Shortcuts for Xcode Keyboard shortcuts may differ between keyboard layouts. Mouseless is smart enough to show the exact keys according to your layout. Docs for Xcode 1.4 for Mac is free to download from our application library. The following versions: 1.2, 1.1 and 1.0 are the most frequently downloaded ones by the program users.

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.

Xcode

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 beyond Error conformance, 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
Precondition
Postcondition
Requires
Invariant
Complexity
Important
Warning
Metadata
Author
Authors
Copyright
Date
SeeAlso
Since
Version
General Notes & Exhortations
Attention
Bug
Experiment
Note
Remark
ToDo

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.

Android 12 Developer Preview is here! Try it out, and give us your feedback!

Whether you're building for Android handsets, Wear OS by Google, Android TV, Android Auto, or Android Things, this section provides the guides and API reference you need.

Get started

Android devices

Best practices

Core developer topics

Design guides

More documentation

Android Architecture Blueprints

A collection of samples to discuss and showcase different architectural tools and patterns for Android apps.

Universal Android Music Player Sample

This sample shows how to implement an audio media app that works across multiple form factors and provide a consistent user experience on Android phones, tablets, Auto, Wear and Cast devices.

Android Architecture Components samples

Samples for Android Architecture Components.

Android testing samples

A collection of samples demonstrating different frameworks and techniques for automated testing.

Topeka for Android

A fun to play quiz that showcases material design on Android.

Android NDK Samples

Android NDK samples with Android Studio.

Android Architecture components

This library provides APIs for essential app architecture tasks like lifecycle management and data persistence, so you can write modular apps with less boilerplate code.

Xcode Help

Support library

The Android Support Library offers backward-compatible versions of a number of features, including others not built into the framework.

Data binding library

The Data Binding Library enables you to write declarative layouts.

Android Test

Android Test helps you build and run test code for your app.

Play Billing Library

The Google Play Billing Library provides a simple interface for sending billing requests and managing billing transactions with Google Play.

Android Emulator

You can install and run your app on the Android Emulator faster than with a physical device. It simulates various device configurations and hardware sensors, and it uses a snapshot to quickly resume exactly where you left off.

Configure your build

Android Studio uses Gradle, an advanced build toolkit, to automate the build process, while allowing you to define flexible, custom build configurations.

Build your UI layout

Android Studio includes a layout editor that allows you to build and preview your app UI by dragging elements into a visual design editor instead of writing layout XML by hand.

Profile your app performance

Poor app performance can ruin the user experience and destroy your app's reputation. If it ever responds slowly, shows choppy animations, freezes, crashes, or consumes a lot of power, your users will notice. To avoid these performance problems, use the Android Profiler to measure your app's memory, CPU, and network usage.

Docs For Xcode Editor

More education

Check out these other resources for beginner and experienced Android developers.

Android codelabs

Codelabs are short, self-paced tutorials that step you through the process of building a particular type of app or adding a new feature to an existing app.

Online video courses

Apple Xcode Guide

Google partnered with Udacity to teach Android development with online videos. Several free courses are available, or you can enroll in the Nanodegree program.

Swift Documentation Comments

Training courses

Docs For Xcode App

These online trainings provide a guided path through the process of learning how to build Android apps. Courses are available for new and advanced developers.
Coments are closed

Recent News

  • CourseForum
  • Show Desktop
  • Keyboard Maestro

Scroll to top