Some XML comment tags require cref attribute which defines reference to other member or file. These are for example <see> and <seealso> tags.
Reference can point to two different types of location:
1.File on current file system or URL.
2.Documentation for some member in current project, solution or .NET Framework.
Reference to a file or URL
It uses href attribute. Referenced files should be placed in external files folder. The path is then relative to that folder.
Example |
///<summary> /// Visit our website: <see href="http://www.helixoft.com" /> ///</summary> ///<seealso href="title.bmp"></seealso> ///<seealso href="examples\example.txt">Example of ExecuteQuery Method</seealso> |
Reference to member in current project, solution or .NET Framework
It adds a link to the documentation for specified member in the project, solution or .NET Framework. Name reference has several formats. The format is adopted from standard XML documentation convention but in addition it also allows several abbreviations.
The first part of the reference string identifies the kind of member being identified, via a single character followed by a colon. The following member types are used:
Character |
Description |
N |
namespace |
T |
type: class, interface, struct, enum, delegate |
F |
field |
P |
property |
M |
method (including such special methods as constructors, and so on) |
E |
event |
O or Overload |
overloads list topic page for a member, in this case you don't specify any parameters |
VSdocman doesn't require to use this special character in most cases. Moreover, you don't need to always specify the full name of member. You can use shorter form instead.
The possible combinations of abbreviated cref format are:
1.
fully-qualified name
It points to the documentation of a member with full name specified. If the member has also parameters you can specify them too. Parameters must be always fully qualified. You can omit parameters if there is no other overloaded method. In this case parameters are not necessary to uniquely identify member.
Example |
<see cref="TestDLL.DllClass1.prop1"></see> |
Points to documentation of prop1 property in DllClass1 class in TestDLL namespace.
Example |
<see cref="TestDLL.DllClass1.method1(System.Int32[], System.String)"> Some interesting method</see> |
It points to the documentation of method1 with two parameters - array of Integers and String. The label is "Some interesting method"
2.
namespace
It points to the namespace documentation.
Example |
<see cref="TestDLL"></see> |
It points to the documentation of TestDLL namespace. If there is a type (class, structure, ...) with the same name TestDLL, you must prefix the reference by N: to distinguish between them.
3.
type
It points to the type (class, structure, ...) in current namespace.
Example |
<see cref="DllClass1"></see> |
It points to the documentation of DllClass1 class. If there is a namespace with the same name DllClass1, you must prefix the reference by T: to distinguish between them.
4.
type.member
It points to the documentation of a member in type (class, structure, ...) in current namespace. Only namespace is missing.
Example |
<see cref="DllClass1.prop1"></see> |
It points to the documentation of prop1 property in DllClass1 class.
5.
member
It points to the documentation of a member in current type (class, structure, ...).
The following example in DllClass1 class points to the documentation of prop1 property in DllClass1 class.
Example |
<see cref="prop1"></see> |
In any format above, if the member has parameters, you can omit them if you want. However, this may lead to disambiguity in the case if there are several overloaded members with the same name but with various parameters. If you do so, VSdocman finds the first member with specified name. Or we recommend to use O: prefix in such case and the link will point to an Overloads page.
Comment editor always generates fully-qualified references with parameters if necessary.
