What is the meaning of XML tags "see "and "seealso" in C# in Visual Studio 2010?

When you work in Visual Studio 2010 and write a comment on a method and click enter Visual Studio 2010 a开发者_如何学编程llows you to create "see" and "see also" XML comments.

If you type in comment "see" and press TAB then it looks like

/// <see cref=""/>
/// <seealso cref=""/> 

What is meaning of it in C#?

---

Both are XML documentation tags that are compiler verified.

<see> is for placing links directly in the text.

<seealso> is to place text in the "See Also" section.

See how they are used in this example.

---

<see /> and <seealso /> started out as completely different tags for entirely different purposes, but today (perhaps in recognition to how confusing the situation was) are treated almost identically, at least when used the way most people interact with them. Obviously both exist so you can link to another type or declaration to cross-link your documentation (or point to an external link), but for anything pertaining to intellisense completions, <see /> is what you were supposed to be using.

Per Microsoft's documentation on in-code XML documentation, and in particular, the section on seealso:

The <seealso> tag lets you specify the text that you might want to appear in a See Also section. Use <see> to specify a link from within text. You cannot nest the seealso tag inside the summary tag. (emphasis added)

See, originally the <see /> tag was for cross-referencing or linking to external resources in the body of what you see in the intellisense completion and <seealso /> served an altogether different purpose: to add a link/footnote to the bottom of the generated HTML documentation, like that you would see in the old-school MSDN docs at the bottom of the page. <seealso /> was not supported within the core <summary>...</summary> tags (what you see in an intellisense popup) and with old versions of the compilers/in old versions of Visual Studio, it would not have rendered the way it does today.

Original <see />-only usage

Here is an xmldoc example using <see /> and how it is rendered in Visual Studio:

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <see cref="FooSpecial" />, you cannot configure the lifetime
/// lifetime of this object.
/// </summary>
public class Foo {}

Today this also works if using <seealso />, as shown here:

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <seealso cref="FooSpecial" />, you cannot configure the
/// lifetime of this object.
/// </summary>
public class Foo {}

If you're linking to external content, instead of having a potentially long-and-unwieldy URL displayed in the body of an intellisense completion:

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <see cref="FooSpecial"/>, you cannot configure the lifetime
/// of this object.<br/><br/>
/// Refer to this article on managing object lifetimes for more information:
/// <see href="https://neosmart.net/blog/tag/C#"/>
/// </summary>

You can instead use the alternative notation to link to text while changing what's shown (just like an <a href="..." /> tag in HTML):

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <see cref="FooSpecial"/>, you cannot configure the lifetime
/// of this object.<br/><br/>
/// Refer to this <see href="https://neosmart.net/blog/tag/C#">
/// article on managing object lifetimes</see> for more information.
/// </summary>
public class Foo { }

Original and Current <seealso />-only usage

All the previous examples work fine with either <see /> or <seealso />, although the actual specifications haven't changed and technically using <seealso /> in that manner is 100% wrong because it is not meant to be nested in a <summary /> block.

So then what purpose does <seealso /> actually serve? It's only natural to try following Microsoft's instructions and use <seealso /> as a top-level tag, and try to see if it renders in intellisense any differently:

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <see cref="FooSpecial"/>, you cannot configure the lifetime
/// of this object.
/// </summary>
/// <seealso href="https://neosmart.net/blog/tag/C#">
/// Refer to this article on managing object lifetimes for
/// more information.
/// </seealso>
public class Foo { }

...only to discover that it does nothing at all when viewed in Visual Studio:

But you have to remember that Microsoft first came up with their version of xmldoc to automatically generate the MSDN documentation directly from the source files - not all the xmldoc features are there for intellisense's use. Now if you were to use an HTML documentation generator (I used fxdoc, which was originally written by Microsoft and is still used by them in some fashion), this is what you'd see:

The purpose of <seealso /> becomes clear - it doesn't directly contribute to the immediate description of the documented project member (the summary tag), but it tells the documentation generator to save the <seealso /> tag for later and to emit it at the bottom of the document in the "See Also" section that it is so cleverly named after!

As a final note, I would not have been surprised to see that replacing <seealso>...</seealso> with <see>...</see> in the final example would have generated the same result because I assumed that Microsoft just decided to treat them identically but render them depending on context (whether they were found in a <summary /> block or as top-level tags), but if you were to try it (at least today, as of docfx version 2.58.9.0) you'll discover at long last actual proof of a difference between the two: no "See Also" section is generated if <see /> is used as a top-level tag:

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <see cref="FooSpecial"/>, you cannot configure the lifetime
/// of this object.
/// </summary>
/// <see href="https://neosmart.net/blog/tag/C#">
/// Refer to this article on managing object lifetimes for
/// more information.
/// </see>
public class Foo { }

---

See and SeeAlso turn into references to other classes in the generated documentation, according to the .NET xml documentation standard.

Please read http://msdn.microsoft.com/en-us/library/5ast78ax.aspx for more information about tags available.

Note that in addition to that, Sandcaslte also supports on subclasses, copying in the documentation from the base class.

---

After so much time I'm surprised nobody has responded with the most important parts of the answer.

Microsoft's standard documentation system, is fueled by special comments tagged with /// or ''' or --- etc depending on language.

By default, the system only feeds intellisense. The XML output created during compilation from these special comments and any supported tags within them can be used as input to other systems such as SandCastle and DocFX but you must install these tools and configure them to benefit from them. If you use such tools, the difference between the two tags is determined by the tool and perhaps how you configure it, not by Microsoft. So read the documentation for the tool in question to understand if the tags are treated differently and, if so, in what way.

Having said that, if you aren't using an external tool you may not see the point of using either tag since there is no obvious reason to do so and no obvious difference between them if you choose to use one or the other.

The truth is, there is currently no difference between them from an intellisense point of view. However there is a very good reason to use one them even if you don't use tools that read the XML output. That reason is REFACTORING!

By tagging an identifier (with see or seealso) as opposed to just typing it's name as literal text, Visual Studio's refactoring tools are informed that the label is a legal identifier. This causes any renaming of the identifier to include the tag content. This has a huge advantage over the often ambiguous string searches that are otherwise necessary to keep documentation in sync with source code when identifiers are renamed.

In a way, it serves a similar function as the nameof() operator, which is useful in building strings. The difference is, this works within ANY specially marked COMMENT rather than in code.

---

Those elements are used for documentation creation. If you look at MSDN you will find several links in class descriptions that refer to other types.

Edit See http://www.sandcastledocs.com/ as a sample app to create those help files.