autorest.csharp: AutoRest fails to produce the expected XML documentation in .NET libraries
ℹ️ Updated: 02 January 2023
Problem
When AutoRest generates C# XML documentation comments in .NET libraries from OpenAPI description files whose description fields contain HTML markup tags, the tags are merely escaped by transforming the tag delimiters into their HTML character entity equivalents. This leads to downstream tools like IntelliSense, DocFx, and other documentation processors rendering unexpected (incorrect) output that doesn’t reflect OpenAPI description file author’s intended formatting.
For example, the angle brackets in HTML tags like <b>, <ul>, and <li> that appear in the description field of OpenAPI descriptions (aka “Swagger files”) are transformed into their character entity equivalents < and > in the XML documentation comments generated by AutoRest.
Duplicate issues:
- https://github.com/Azure/azure-sdk-for-net/issues/27039
- https://github.com/Azure/autorest.csharp/issues/1547
- https://github.com/Azure/azure-sdk-for-net/issues/32386
Expected
- AutoRest generates well-formed XML in C# doc comments per the C# language specification.
- AutoRest generates doc comments that reflect the OpenAPI description author’s intent.
- AutoRest has markup support parity with OpenAPI 2.0 and 3.0 specifications.
- Specifically for this issue is parity support for handling the markup that appears in the
descriptionfield of applicable entity types defined in an OpenAPI description file.
- Specifically for this issue is parity support for handling the markup that appears in the
Expected behavior: two options
There are a couple options I can think of that might be considered as a fix:
- Expected behavior option 1: atomic tag transform 👈 preferred
- Transform each HTML tag found in the OpenAPI description file’s
descriptionfields into their XML-compliant equivalents like<para>and<list>when generating C# XML documentation comments in .NET libraries. - More info in comment https://github.com/Azure/autorest.csharp/issues/208#issuecomment-461630640
- Transform each HTML tag found in the OpenAPI description file’s
- Expected behavior option 2: CDATA
- Enclose the entire contents of the OpenAPI description file’s
descriptionfields within XML CDATA tags when generating C# XML documentation comments in .NET libraries. - More info in comment https://github.com/Azure/autorest.csharp/issues/208#issuecomment-1046056381
- Enclose the entire contents of the OpenAPI description file’s
Encountered
OpenAPI description (Swagger file) - description field of adminUsername from Microsoft.Compute/stable/2022-03-01/ComputeRP/computeRPCommon.json#L1360
"description": "Specifies the name of the administrator account. <br><br> This property cannot be updated after the VM is created. <br><br> **Windows-only restriction:** Cannot end in \".\" <br><br> **Disallowed values:** \"administrator\", \"admin\", \"user\", \"user1\", \"test\", \"user2\", \"test1\", \"user3\", \"admin1\", \"1\", \"123\", \"a\", \"actuser\", \"adm\", \"admin2\", \"aspnet\", \"backup\", \"console\", \"david\", \"guest\", \"john\", \"owner\", \"root\", \"server\", \"sql\", \"support\", \"support_388945a0\", \"sys\", \"test2\", \"test3\", \"user4\", \"user5\". <br><br> **Minimum-length (Linux):** 1 character <br><br> **Max-length (Linux):** 64 characters <br><br> **Max-length (Windows):** 20 characters."
AutoRest-generated source code - OSProfile.cs
/// <summary> Specifies the name of the administrator account. <br><br> This property cannot be updated after the VM is created. <br><br> **Windows-only restriction:** Cannot end in "." <br><br> **Disallowed values:** "administrator", "admin", "user", "user1", "test", "user2", "test1", "user3", "admin1", "1", "123", "a", "actuser", "adm", "admin2", "aspnet", "backup", "console", "david", "guest", "john", "owner", "root", "server", "sql", "support", "support_388945a0", "sys", "test2", "test3", "user4", "user5". <br><br> **Minimum-length (Linux):** 1 character <br><br> **Max-length (Linux):** 64 characters <br><br> **Max-length (Windows):** 20 characters. </summary>
How it’s rendered Intellisense:
Rendered on docs.microsoft.com - OSProfile.AdminPassword:
About this issue
- Original URL
- State: open
- Created 5 years ago
- Comments: 21 (11 by maintainers)
@danieljurek only option1 is sustainable to me.
For instance with Python:
I feel C# needs something like that.
CC @AlexanderSher
Sorry @danieljurek, no, I have not manually tested the proposed changes.
Apologies for the delay in response, as well. I moved on from Microsoft at the end of October and got caught up in the switch-to-a-new-company-and-new-job thing, and your question got lost in the fray.
On that note, there’ll likely be no change in testing status from me on this issue, but I’ll certainly continue following it. 🙂
ping… any update on this?
Plan B would be doc team process “summary” as a big bloc of Markdown/HTML instead of the expected summary XML format. That could be a pragmatic way to solve it, but then we should keep in mind that we tight a particular MS-specific output to a particular specific MS-specific doc input.
And I throw myself under the bus for Python as well, this is the only reason why Python doc works: I write Markdown in my DocString (where I should write RST only), and it works just because Doc team happen to parse it by chance. So again, I really don’t say it’s trivial to do this transformation.
Ok, thought “summary” was a place holder for TEXT (CDATA like) but it’s actually a proper XML language.
For that I see, there need to be a translation from Markdown to this XML format.
Example:
should be (ref)
or this:
should be (ref from ScottHa)
Again, I’m not a C# dev but this is my understanding of the XML spec.
And yes, it’s not trivial, I never said that…