Guides and Sample Code

Developer

Markup Formatting Reference

On This Page

Formatting Quick Help

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 3.1).

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.

image: ../Art/MFR_code_quick_help_2x.png

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.
  3.  *Values*
  4.  `NegativeCount` The count is less than 0.
  5.  `EmptyString1` The first string argument is empty.
  6.  `EmptyString2` The second string argument is empty.
  7.  - Author:
  8.    Newbie
  9.  - Version:
  10.    0.1
  11. */
  12. enum FakeArrayError: ErrorType {…
Figure 5-1Sections in Quick Help image: ../Art/MFR_symbol_section_description_2x.png

Parameters Section

Use the Parameter and Parameters delimiters to add the parameters section to Quick Help. If the markup for a symbol use both delimiters, Quick Help shows all of the Parameters entries followed by all of the Parameter entries. The order for the parameters is the same as the order they appear in the markup.

Returns Section

Use the Returns delimiter to add the returns section to Quick Help.

Throws Section

Use the Throws delimiter to add the throws section to 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.

  1. /**
  2.  *A description field*
  3.  - important: This is
  4.    a way to get the
  5.    readers attention for
  6.    something.
  7.  - returns: Nothing
  8.  *Another description field*
  9.  - version: 1.0
  10. */
Figure 5-2Callouts in Quick Help image: ../Art/MFR_symbol_description_field_2x.png