迅捷注释“标签”

Question

自从Objective-C起，我就是#pragma MARK:的粉丝，但是最近我在Apple的源代码中看到了/// -Tag:。同样值得注意的是，它以白色突出显示，而MARK不是。另一边的Tag不会在Xcode的“大纲”视图中添加任何文本。

有人能解释Tag的目的是什么吗？

Answer 1

我无法找到特定于Tag文档关键字的任何内容。它似乎是一个自定义文档关键字，尽管它没有像预期的那样出现在快速帮助中。

我猜想它可能只是允许搜索相关代码的一种方法...也许将来它会作为一项新功能出现-像您一样将“标记”应用于特定符号在Finder中说。鉴于问题中引用的功能与自定义群集相关（请参阅Decluttering a Map with MapKit Annotation Clustering），文档行显示/// - Tag: CustomCluster，这似乎是合理的。

---

编写函数时，可以使用“ markdown”版本在Swift中记录该函数的详细信息。有关示例，请参见Markup Formatting Reference和CommonMark。

此文档显示在 Quick Help 弹出框（如问题所示）中，并且显示在 Quick Help Inspector 中-当您的光标显示在右侧面板中时在符号中（例如，函数名称），然后单击检查器面板顶部的圆圈中的问号。

此文档存在许多预定义的关键字，例如- Parameters:，- Returns:和- Throws:。并且，您也可以使用自己的自定义关键字。通常，自定义关键字也会出现在快速帮助中，但是这个- Tag:关键字似乎没有任何作用（至少在Xcode 9.4.1中如此）。

以下是如何使用Swift文档标记的示例：

/// 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
}

然后，在快速帮助检查器中，您将看到：

或者，当然，在功能名称上单击鼠标右键将显示快速帮助弹出框：

问题中指出，- Tag:关键字在快速帮助检查器或快速帮助弹出窗口中均不显示任何内容。

Answer 2

可以使用MaterialFormsTextInputLayout注释来引用您自己的代码的某些位置，并且它是快速文档降价语法的一部分。这是一个简化的示例：

public class EntryRendererForAndroid : MaterialEntryRenderer
{
    public EntryRendererForAndroid(Context context) : base(context)
    {

    }

    protected override void OnElementChanged(ElementChangedEventArgs<Entry> e)
    {

        base.OnElementChanged(e);

        Control.EditText.SetTextCursorDrawable(Resource.Drawable.my_cursor);

    }
}

打开- Tag:的快速帮助弹出窗口时，单击/// - Tag: myFunction func myFunction() { print("My function is called") } /// Uses [myFunction](x-source-tag://myFunction) internally func anotherFunction() { myFunction() } 链接，它将带您到在代码中使用anotherFunction的地方< / p>