2009-03-28 11 views
44

<see cref="switch" />, por ejemplo, no funciona - tengo la advertencia de compilación: XML comment on ... has syntactically incorrect cref attribute 'switch'¿Cómo hago referencia a una palabra clave C# en la documentación XML?


Contexto para aquellos que estén interesados ​​...

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

La etiqueta en cuestión puede se encuentra en la etiqueta <remarks> para SerializeProperty. Me estoy equivocando del lado de la documentación detallada. También planeo proporcionar algunos <example> s, aún no me he enterado.

Respuesta

64

CREF se entiende que se refiere a otro miembro - una clase, un método etc.

qué se puede esperar que establecer el vínculo en este caso? En general, ¿qué quieres que sea el efecto general?

De acuerdo con esta excellent XML doc guide, la etiqueta tiene un atributo <see> indocumentado langword:

<see langword="switch" /> 

¿Eso le ayuda? Puede valer la pena intentarlo solo para ver qué hace.

Si lo que desea es utilizar un hipervínculo normal, use href lugar de CREF:

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

El artículo de MSDN para la palabra clave interruptor: http://msdn.microsoft.com/en-us/library/ 06tc147t.aspx –

+0

¡Incluso funciona para VB.NET dentro de un proyecto de C#! Para implementarlo, use un ( en VB.NET) –

+0

Tengo que admitir que nunca antes había visto ese atributo. Solo sabía de la página, y vi lo que tenía que decir por sí mismo :) –

Cuestiones relacionadas