<see> xml doc topic doesn't mention the href attribute

[mairaw]

The syntax on the topic only shows <see cref="member"/> but not the see href syntax:
<see href="url">link text</see>

edit: added topic details

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 7c9f2f59-0dec-c531-b19a-a2109ea0f973
• Version Independent ID: 74c6022c-8661-216e-4f48-e5f08f432f85
• Content: <see> - C# Programming Guide
• Content Source: docs/csharp/programming-guide/xmldoc/see.md
• Product: dotnet-csharp
• GitHub Login: @BillWagner
• Microsoft Alias: wiwagn

[eduard-malakhov]

@mairaw Is there a standard or another technical document we can refer to to make sure that that syntax is/must be supported too? I've made a quick research and here's what I found:

• Doxygen documentation only mentions the <see cref=""/> syntax;
• Sandcastle does mention <see href=""/> as a means to support external links; besides that, Sandcastle also supports the following: <see langword=""/>;
• In my VS2017 version 15.5.2 autocompletion only offers one option for <see ... and it's <see cref=""/> (although <see href=""/> is processed and emitted in the XML as expected).

So, there's definitely more than one view on this and we might need some reference to determine which one is correct.

I guess, if we are positive that <see href=""/> must be described in the programming guide, we might also want to fix autocompletion if VS. Also, shall we consider <see langword=""/> for the guide too?

[mairaw]

Good points @eduard-malakhov! I'm not sure about the technical docs that show the ones that must be supported. The docs here seem to match the common options covered in the C# spec: https://github.com/dotnet/csharplang/blob/master/spec/documentation-comments.md#recommended-tags

Yes, if we add see href, we should also add see langword. VS IntelliSense does recognize those even though it doesn't offer them as an option when you're doing the /// commments.

@BillWagner @jcouv @gafter any thoughts on this?

[eduard-malakhov]

@mairaw regarding this

VS IntelliSense does recognize those even though it doesn't offer them as an option when you're doing the /// commments.

I can say that in my VS2017 IntelliSense reports no errors even on the following code.

using System;

namespace ConsoleApp4
{
    /// <summary>
    /// <see attribute=""/>
    /// </summary>
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
        }
    }
}

And even generates a documentation file.

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>ConsoleApp4</name>
    </assembly>
    <members>
        <member name="T:ConsoleApp4.Program">
            <summary>
            <see attribute=""/>
            </summary>
        </member>
    </members>
</doc>

Is it possible that IntelliSense does not validate documentation comments?

[mairaw]

There were also some discussions around having the same docs available for VB. @KathleenDollard we'll need to sync to understand what are the options supported by VB.

[jcouv]

From my experimentation, it looks like VS supports langword (it is offered as completion, it has its own completion list and it is displayed nicely in QuickInfo).
For href, there doesn't seem to be any support at the moment (C#/VB compilers or VS). If other tools support it, then we should file a request in Roslyn repo to support in IDE).

[KathleenDollard]

Do we know anything about how much usage Doxygen and Sandcastle each get?

I am a bit hesitant to include a feature that will be ignored by some tools.

[BillWagner]

Do we know anything about how much usage Doxygen and Sandcastle each get?

No, and I'm not sure how we could get reliable info on their usage.