@see reference [label]
It adds a link, with visible text label, that points to the documentation for the specified reference. Warning appears during compilation if reference points to non-existing target. The label is optional. If omitted, instead of it the reference appears as the visible text. Use the label when you want the visible text to be abbreviated or different from the reference. It can contain whitespaces.
Reference can point to two different types of location:
It starts with ^ character or double quote. The file name follows immediately without any space between them. No whitespace is allowed within the file name. The path is relative to generated file.
Example:
'** '@see ^title.bmp '@see ^c:\MyPics\example.txt Example of ExecuteQuery Method
This generates 2 links pointing to specified files:
See Also
title.bmp | Example of ExecuteQuery Method
It adds a link to the documentation for specified member in VB project. Name reference has several formats. The format is adopted from C# 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 |
Unlike the C# comments, 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 are:
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 TestDLL.DllClass1.prop1
Points to documentation of prop1 property in DllClass1 class in TestDLL namespace.
@see TestDLL.DllClass1.method1(System.Int32(), System.String) Some interesting method
It points to the documentation of method1 with two parameters - array of Integers and String. The label is "Some interesting method"
namespace
It points to the namespace documentation.
Example:
'** '@see TestDLL
It points to the documentation of TestDLL class. If there is a type (class, structure, ...) with the same name TestDLL, you must prefix the reference by N: to distinguish between them.
type
It points to the type (class, structure, ...) in current namespace.
Example:
'** '@see DllClass1
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.
type.member
It points to the documentation of a member in type (class, structure, ...) in current namespace. Only namespace is missing.
Example:
@see DllClass1.prop1
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, ...).
Example:
in DllClass1 class:
@see .prop1
It points to the documentation of .prop1 property in DllClass1 class.
Every time in any format above if you specify a member that 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.
Comment editor always generates fully-qualified references with parameters if necessary.