Làm cách nào để tham chiếu từ khóa C# trong tài liệu XML?

Question

<see cref="switch" />, ví dụ, không hoạt động - Tôi nhận được cảnh báo biên soạn: XML comment on ... has syntactically incorrect cref attribute 'switch'

---

bối cảnh cho những ai quan tâm ...

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

---

Thẻ trong câu hỏi có thể được tìm thấy trong thẻ <remarks> cho SerializeProperty. Tôi đang ở phía bên kia của tài liệu chi tiết. Tôi cũng có kế hoạch cung cấp một số <example> s, tôi chỉ chưa nhận được xung quanh để nó được nêu ra.

Answer 1

cref là có nghĩa là để chỉ một thành viên khác - một lớp học, một phương pháp, vv

gì bạn mong chờ nó liên kết đến trong trường hợp này? Nói chung, bạn muốn tác động tổng thể là gì?

Theo excellent XML doc guide này, thẻ <see> có một thuộc tính không có giấy tờ langword:

<see langword="switch" /> 

Would giúp bạn? Nó có thể là giá trị cố gắng nó chỉ để xem những gì nó làm.

Nếu bạn chỉ muốn sử dụng một siêu liên kết bình thường, sử dụng href thay vì cref:

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