如何在XML文档中引用C#关键字? [英] How do I reference a C# keyword in XML documentation?
问题描述
<see cref="switch" />
不起作用-我收到编译警告:XML comment on ... has syntactically incorrect cref attribute 'switch'
<see cref="switch" />
, for example, doesn't work - I get the compilation warning: 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;
}
}
有问题的标签可以在SerializeProperty
的<remarks>
标签中找到.我在冗长的文档方面犯了错误.我还计划提供一些<example>
,但我还没有解决.
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.
推荐答案
cref旨在引用另一个成员-类,方法等.
cref is meant to refer to another member - a class, a method etc.
在这种情况下,您希望它链接到什么?一般来说,您希望整体效果如何?
What would you expect it to link to in this case? In general, what do you want the overall effect to be?
据此优秀的XML文档指南,<see>
标签具有未记录的属性langword
:
According to this excellent XML doc guide, the <see>
tag has an undocumented attribute langword
:
<see langword="switch" />
这对您有帮助吗?仅仅看看它做什么可能值得尝试.
Would that help you? It might be worth trying it just to see what it does.
如果您只想使用普通的超链接,请使用href而不是cref:
If you just want to use a normal hyperlink, use href instead of cref:
<see href="http://msdn.microsoft.com/en-us/library/06tc147t.aspx">switch</see>
这篇关于如何在XML文档中引用C#关键字?的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!