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?

Just a terminology note: the `#pragma MARK:` (or `// MARK:` in Swift) is a way to organize your code. You can search for marks in the *jump bar* at the top of Xcode (click on the class or struct name to see the symbols in your object). `/// - Tag:` is an item for *Quick Help* display - which allows you to document, or see documented, as in this case, information regarding a specific symbol (function or variable). Though they both are forms of documentation, they have very different purposes and functionality. — leanne, Jul 26 '18 at 15:32
Does this answer your question? [How to go about adding a link/reference to another method in documentation Xcode?](https://stackoverflow.com/questions/38321880/how-to-go-about-adding-a-link-reference-to-another-method-in-documentation-xcode) — The Dreams Wind, Sep 04 '22 at 17:02
Sure, but that's the new stuff. Back in 2018, when there where dinosaurs, we didn't had such fanciness. — Carsten, Nov 11 '22 at 16:02

The Dreams Wind · Accepted Answer · 2022-09-02T20:52:16.183

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:

leanne · Answer 2 · 2018-07-26T17:00:29.160

I haven't been able to find anything specific to the Tag documentation keyword. It appears to be a custom documentation keyword, though it doesn't appear in Quick Help as expected...

I'm guessing that it may just be a way to allow searching for related code... Maybe it'll come up as a new feature in the future - used to apply "tags" to specific symbols, as you would in Finder, say. That seems reasonable, given that the function referenced in the question is related to custom clustering (see Decluttering a Map with MapKit Annotation Clustering), and the documentation line says /// - Tag: CustomCluster.

When you write a function, you can document the details of that function in Swift using a version of "markdown". See the Markup Formatting Reference and CommonMark for examples.

This documentation appears in the Quick Help popover box, as shown in the question, and in the Quick Help Inspector - displayed in the right-hand panel when your cursor is in a symbol (function name, for example), and you click the question mark in a circle at the top of the inspector panel.

Many pre-defined keywords exist for this documentation, such as - Parameters:, - Returns:, and - Throws:. And, you can also use your own custom keywords. Usually the custom keywords appear in the Quick Help as well, but this - Tag: keyword doesn't seem to do anything (at least in Xcode 9.4.1).

Here's an example of how to use Swift Documentation Markup:

/// Errors associated with String processing.
enum StringError: Error {
    case cantCapitalizeAnEmptyString
}

/// Capitalizes a String item.
/// - Tag: I don't know what this is - it doesn't show in Quick Help.
/// - Parameter string: A String item to be capitalized.
/// - Throws `StringError.cantCapitalizeEmptyString` when provided String item is empty.
/// - Returns: The provided String item converted to all capital letters.
/// - Blah: A custom keyword I made up.
func capitalize(string: String) throws -> String {
    if string.isEmpty {
        throw StringError.cantCapitalizeAnEmptyString
    }
    return string.capitalized
}

Then, in the Quick Help Inspector, you'll see:

Or, of course, option-clicking the function name will display the Quick Help popover:

As noted in the question, the - Tag: keyword doesn't display anything in either the Quick Help Inspector or the Quick Help popover.

Swift annotation "Tag"

2 Answers2

Linked