Use markup to create richly formatted Quick Help for any symbol in your Swift code. Symbols include named classes, methods and functions, enumerated types, and other named constructs. For more information on named constructs in Swift, see Declarations in The Swift Programming Language (Swift 2.2).

Xcode Quick Help

Quick Help for a symbol is shown by Option-clicking a symbol. It is also shown in the Quick Help inspector in the utilities area when the insertion point is in a symbol. Symbol information is categorized into sections such as Description and Parameters. The description section can contain information callouts such as the version. The following figure shows the Quick Help pop-up and the Quick Help inspector pane for the coreFields function.

Quick Help Sections

Quick Help content is grouped into named sections of related information such as the parameters of a method. The following descriptions are added using markup delimiters:

• The Descriptionsection gives a description of the symbol such as the purpose of a method.

• The Parameters section lists the parameters for a method or function.

• The Throws section documents any errors thrown by a method or function.

• The Returns section documents any return value for a method or function.

The parameters, throws, and returns sections are added using specific markup delimiters.

Description Section

The description section is composed of any lines of markup that are not part of another section delimiter. Parts of the description can occur both before and after section delimiters. The order of the rendered content in the description section is the same as the order it appears in the markup.

For example, the following markup renders the description section shown in shown in Figure 5-1.

1. /**
2.  Errors thrown by fakeArray.
4.  *Values*
6.  `NegativeCount` The count is less than 0.
8.  `EmptyString1` The first string argument is empty.
10.  `EmptyString2` The second string argument is empty.
12.  - Author:
13.    Newbie
14.  - Version:
15.    0.1
16. */
18. enum FakeArrayError: ErrorType {…

Figure 5-1Sections in Quick Help

Adding Callouts

Markup includes many callout delimiters that add useful information about your Swift symbols such as authors, required preconditions, and warnings. The content for the callouts appears in the description section for the symbol in Quick Help.

For example, the markup below adds Important and Version callouts resulting in the Quick Help shown in Figure 5-2. The important callout starts on line 2. The version callout is on line 11, after the callout for the Returns section.

Figure 5-2Callouts in Quick Help