C#: <see> tags generated from externalDocs are missing link text

[brjohnstmsft]

Currently AutoRest generates <see> tags without link text, which doesn't render correctly when translated directly to <a href> tags. For example, this Swagger (from here):

    "externalDocs": {
        "url": "https://docs.microsoft.com/rest/api/searchservice/Update-Data-Source"
    },

generates this <see> tag (from here):

/// <see href="https://docs.microsoft.com/rest/api/searchservice/Update-Data-Source" />

When publishing SDK docs to docs.microsoft.com, the <see> tag is translated into this:

<a href="https://docs.microsoft.com/rest/api/searchservice/Update-Data-Source"></a>

The missing text causes the link to fail to render. While this can and should be fixed on the doc publishing side, it could also help if AutoRest produces <see> tags with link text. The simplest solution would be to just copy the link itself, like this:

/// <see href="https://docs.microsoft.com/rest/api/searchservice/Update-Data-Source">https://docs.microsoft.com/rest/api/searchservice/Update-Data-Source</see>

This wouldn't require any changes to existing Swagger specs. In addition to this, AutoRest could include support for the description property of the externalDocs object, so that spec authors can specify their own link text.

[brjohnstmsft]

@fearthecowboy There's been no response on this for 6 months. Has this been triaged?

[fearthecowboy]

We're currently saturated doing work for PowerShell.

At this point, unless it's a critical blocking bug, we're not likely to get back to them until summer when we re-engineer the C# generator

[brjohnstmsft]

@fearthecowboy Thanks for the update.

[brjohnstmsft]

This issue is still causing customer pain: https://github.com/Azure/azure-sdk-for-net/pull/17825

What's the status of this?

[pakrym]

We are scoping down the investment in V2 generator to free up resources for V3/Track 2 work. I'll move this issue to V3 so we can fix it there.