JPMartha's Pancake

This blog is the way to brush up my poor English.

Enumeration Documentation Comments Examples

Overview

This article describe the Markup Formatting for Xcode quick help.

I introduce several Swift symbols.

Motivation

  • I tried using markup formatting commands for descriptions of my library, EggsBenedict. 😊

  • After taking everything into consideration, I don't use anymore now. 😅

  • I might as well introduce how they are displayed. 😁

Examples

The following examples are an enumeration documentation.

Parameters commands

An enumeration is not included in Symbol Section Commands. So I tried using the Parameters commands.

/**
- parameters:
  - NoInstagramApp: Not found Instagram app.
  - UTIIsEmpty: UTI is empty.
  - CannotManipulateImage: Cannot manipulate image.
  - CannotSaveImage: Cannot save image.
  - ImagePathIsEmpty: ImagePath is empty.
*/

f:id:JPMartha:20160116170231p:plain

Bulleted Lists and Code Voice

  • Bulleted lists use an asterisk (*), plus sign (+), or hyphen (-) to delimit each item.
  • Format text as code by using a backquote (`) at the beginning and end of the string.
/**
- `NoInstagramApp`

  Not found Instagram app.

- `UTIIsEmpty`

  UTI is empty.

- `CannotManipulateImage`

  Cannot manipulate image.

- `CannotSaveImage`

  Cannot save image.

- `ImagePathIsEmpty`
  
  ImagePath is empty.
*/

f:id:JPMartha:20160116170341p:plain

Code Voice and Emphasis (Italics)

  • Add emphasis by using an asterisk (*) or underscore (_) at the start and end of the string.
/**
_`NoInstagramApp`_

Not found Instagram app.

_`UTIIsEmpty`_

UTI is empty.

_`CannotManipulateImage`_

Cannot manipulate image.

_`CannotSaveImage`_

Cannot save image.

_`ImagePathIsEmpty`_

ImagePath is empty.
*/

f:id:JPMartha:20160116171324p:plain

Code Voice and Strong (Bold)

  • Add strong formatting with two asterisks (**) or two underscores (__) at the start and end of the string.
/**
__`NoInstagramApp`__

Not found Instagram app.

__`UTIIsEmpty`__

UTI is empty.

__`CannotManipulateImage`__

Cannot manipulate image.

__`CannotSaveImage`__

Cannot save image.

__`ImagePathIsEmpty`__

ImagePath is empty.
*/

f:id:JPMartha:20160116171406p:plain

Code Voice, Strong (Bold) and Emphasis (Italics)

/**
___`NoInstagramApp`___

Not found Instagram app.

___`UTIIsEmpty`___

UTI is empty.

___`CannotManipulateImage`___

Cannot manipulate image.

___`CannotSaveImage`___

Cannot save image.

___`ImagePathIsEmpty`___

ImagePath is empty.
*/

f:id:JPMartha:20160116171144p:plain

Code Voice and Strong (Bold) written on a single line

/**
__`NoInstagramApp`__: Not found Instagram app.

__`UTIIsEmpty`__: UTI is empty.

__`CannotManipulateImage`__: Cannot manipulate image.

__`CannotSaveImage`__: Cannot save image.

__`ImagePathIsEmpty`__: ImagePath is empty.
*/

f:id:JPMartha:20160116170944p:plain

Code Voice without an enumerarion description

/**
`.NotFoundInstagramApp`

`.UTIisEmpty`

`.CannotManipulateImage`

`.CannotSaveImage`

`.ImagePathIsEmpty`
*/

f:id:JPMartha:20160116171436p:plain

Discussion

Eventually, I don't use anymore. Because when I type the following:

SharingElowError.

f:id:JPMartha:20160116172936p:plain

the enumerations are displayed.

NOTE

I renamed an enumeration names after describing above examples.

Even though I try writing the description of each enumeration, it is not displayed.

By the way, be careful about Symbol and Playground Syntax Differences.

Symbol and Playground Syntax Differences

There are some differences between rich comments in playground and symbol documentation markup syntax including the delimiters. For the playground comment specific syntax and delimiters, see Playground Rich Comments Markup Syntax. For the symbol documentation specific syntax and delimiters, see Symbol Documentation Markup Syntax.

Reference

github.com

developer.apple.com

swift.org