Swift annotation "tag"

Question

Since Objective-C I'm a fan of #pragma MARK: but recently I've seen /// -Tag: in Apple's source code. Also noteworthy, it's highlighted in white, while MARK isn't. Tag on the other side does not add any text to the Xcode 'outline' view.

Can anyone explain what the purpose of Tag is?

Answer 1

The - Tag: annotation can be used in order to make a reference to some places of your own code and is part of swift documentation markdown syntax. Here is a simplified example:

/// - Tag: myFunction
func myFunction() {
  print("My function is called")
}

/// Uses [myFunction](x-source-tag://myFunction) internally
func anotherFunction() {
  myFunction()
}

When you open Quick Help popover of anotherFunction you click the myFunction link and it will take you to the place where - Tag: myFunction is used in code

Answer 2

The - Tag: annotation is used to locate specific places of your own code. You can include it as part of symbols documentation in Swift. E.g. you may add a Tag marker in some Swift file next to a function:

/// - Tag: myFunction
func myFunction() {
  print("My function is called")
}

In another file you can refer to this exact place in the code as part of another Swift entity documentation:

/// Uses [myFunction](x-source-tag://myFunction) internally
func anotherFunction() {
  myFunction()
}

When using the Quick Help popover on anotherFunction in Xcode, you get an interactive reference (under myFunction text), which takes you to the file (and line) where the /// - Tag: myFunction is located: