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

Question

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 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.

<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-wieldy 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 { }

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.