如何在 XML 文档中引用 C# 关键字？

How do I reference a C# keyword in XML documentation?

提问by Daniel Schaffer

<see cref="switch" />, for example, doesn't work - I get the compilation warning: XML comment on ... has syntactically incorrect cref attribute 'switch'

<see cref="switch" />，例如，不起作用 - 我收到编译警告： XML comment on ... has syntactically incorrect cref attribute 'switch'

---

---

Context for those who are interested...

有兴趣的人的背景......

/// <summary>Provides base functionality for hand-coded abstractions of API method wrappers, mostly those that abstract over
/// parameters that are required to be JSON-encoded.</summary>
public class FacebookArgs : Dictionary<String, Object>
{
    /// <summary>Initializes an instance of <see cref="FacebookArgs" />.</summary>
    public FacebookArgs() { }

    /// <summary>Intializes an instance of <see cref="FacebookArgs" />, that contains elements copied from <paramref name="dictionary "/>.</summary>
    /// <param name="dictionary"></param>
    public FacebookArgs(IDictionary<String, Object> dictionary)
        : base(dictionary) { }

    /// <summary>Gets or sets the value associated with the specified key.</summary>
    /// <param name="key">The key of the value to get or set.</param>
    /// <returns>The value associated with the specified key.</returns>
    /// <remarks>This implementation hides the base indexer implementation such that specifying a key that does not exist returns null rather than throwing a <see cref="KeyNotFoundException" />.</remarks>
    public new Object this[String key]
    {
        get
        {
            Object value;
            if (this.TryGetValue(key, out value)) return value;
            else return null;
        }
        set { base[key] = value; }
    }

    /// <summary>In derived classes, provides specialized serialization logic for specific properties contained in this object.</summary>
    /// <param name="key">The key of the property to serialize.</param>
    /// <param name="args">A reference to a dictionary of arguments that will be passed directly to a <see cref="FacebookRequest" /> object.</param>
    /// <remarks>
    /// <para>This method allows specialized serialization logic, such as JSON encoding, to be applied to specific properties.</para>
    /// <para>To implement, use a <c>switch</c> (<c>Select</c> in VB.NET) statement to filter based on <paramref name="key" /> and provide the property-specific logic.
    /// The resulting value should then be added to <paramref name="args" /> using the same <paramref name="key "/>.
    /// </para>
    /// <para>Properties that do not require additional processing (strings, integral values, etc) should be ignored.</para>
    /// </remarks>
    protected virtual void SerializeProperty(String key, ref IDictionary<String, Object> args) { }

    /// <summary>Returns a dictionary of key/value pairs suitable to be passed a <see cref="FacebookRequest" /> object.</summary>
    /// <returns>A dictionary of key/value pairs suitable to be passed a <see cref="FacebookRequest" /> object.</returns>
    /// <remarks>This method calls the <see cref="SerializeProperty" /> for each key in the object, which allows property-specific processing
    /// to be done on any property.</remarks>
    /// <seealso cref="SerializeProperty" />
    public IDictionary<String, Object> GetArgs()
    {
        IDictionary<String, Object> args = new Dictionary<String, Object>();

        foreach (String key in this.Keys)
        {
            this.SerializeProperty(key, ref args);

            if (!args.ContainsKey(key) && this[key] != null)
            {
                args.Add(key, this[key]);
            }
        }

        return args;
    }
}

---

---

The tag in question can be found in the <remarks>tag for SerializeProperty. I'm erring on the side of verbose documentation. I also plan on providing some <example>s, I just haven't gotten around to it yet.

有问题的标签可以在 的<remarks>标签中找到SerializeProperty。我在详细文档方面犯了错误。我也计划提供一些<example>s，我只是还没有得到它。

采纳答案by Jon Skeet

cref is meant to refer to another member - a class, a method etc.

cref 是指另一个成员 - 一个类，一个方法等。

What would you expect it to link to in this case? In general, what do you want the overall effect to be?

在这种情况下，您希望它链接到什么？一般来说，您希望整体效果如何？

According to this excellent XML doc guide, the <see>tag has an undocumented attribute langword:

根据这个优秀的 XML 文档指南，该<see>标签有一个未记录的属性langword：

<see langword="switch" />

Would that help you? It might be worth trying it just to see what it does.

这对你有帮助吗？只是为了看看它的作用可能值得尝试。

If you just want to use a normal hyperlink, use href instead of cref:

如果您只想使用普通超链接，请使用 href 而不是 cref：

<see href="http://msdn.microsoft.com/en-us/library/06tc147t.aspx">switch</see>