我该如何在XML文档中引用C#关键字?

81

<see cref="switch" /> 的用法是不正确的,会导致编译警告: XML comment on ... has syntactically incorrect cref attribute 'switch'

/// <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;
    }
}
该标签可以在SerializeProperty的标签中找到。我倾向于提供详细的文档说明。我也计划提供一些示例,只是还没有做到。
1个回答

133

cref旨在引用另一个成员 - 一个类、一个方法等。

在这种情况下,您希望它链接到什么?总的来说,您希望整体效果是什么?

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

<see langword="switch" />

这会对你有所帮助吗?或许值得尝试一下,看看它能做什么。

如果你只想使用普通超链接,请使用 href 而不是 cref:

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

它甚至可以在C#项目中使用VB.NET!要实现这一点,使用<see langword="switch" />(在VB.NET中为<see langword="Select" />)。 - Daniel Schaffer
2
我必须承认,我以前从未见过那个属性。我只知道这个页面,并看到它自己所说的 :) - Jon Skeet
2
我猜 <see>...</a> 是一个打字错误。<see href="link"></see><a href="link"></a> 都适用于普通超链接(在 Sandcastle 中测试:SHFB)。 - fedab
@fedab 或者 <see href="link"/> 简称 - Kevin
6
来自未来的问候,当时微软文档中使用<see langword="..."/> - Matt Thomas
很不错的是,在 IntelliSense 文档中,你可以得到带颜色的关键字。可惜的是,它不能自动在不同语言之间进行翻译(例如,在 C# 项目中定义了 <see langword="null"/>,如果你在 VB 项目中引用该项目,你仍然会看到 "null" 而不是 "Nothing"),但或许有一天会实现... - Szybki

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接