fix: Render <important> and <note> XML doc tags in generated API reference by AlexDaines · Pull Request #4353 · aws/aws-sdk-net

AlexDaines · 2026-03-13T04:24:48Z

Description

Add handling for <important> and <note> XML doc tags in the doc generator's HTML transformation pipeline. These tags appear across 2,583+ occurrences in the SDK's XML documentation corpus but were previously passed through as unrecognized elements. They now render as styled <div class="noteblock"> blocks with an appropriate header (Important: or Note:).

Motivation and Context

Service teams use <important> and <note> tags in their API model documentation to highlight critical information. The doc generator was silently passing these through as raw <important>/<note> HTML elements, which browsers ignore as unknown tags — the content rendered as unstyled inline text with no visual distinction.

Testing

Dry-run - Powershell5

Dry-run (build) ID: DRY_RUN-74b028b4-df80-443f-8f11-5c997bcf9c45
Status:
- Pending
- Completed successfully
- Failed
Failed bypass reason:

Dry-run - Dotnet4

Dry-run (build) ID: DRY_RUN-7db66e91-4d87-448b-bfa5-382f29243673
Status:
- Pending
- Completed successfully
- Failed
Failed bypass reason:

5 unit tests added in NDocUtilitiesHtmlTests.cs, all using exact output assertions (Assert.Equal):

ImportantTag_RendersAsNoteblock — standard <important> with inner <para>
NoteTag_RendersAsNoteblock — standard <note> with inner <para>
ParaTag_StillRendersAsParagraph — regression test for existing element mapping
SelfClosingImportantTag_ProducesEmptyNoteblock — self-closing <important /> edge case
ImportantTagWithInnerMarkup_PreservesNestedElements — <c> tags nested inside callout, matching real corpus patterns

All 10 tests in SDKDocGenerator.UnitTests pass.

Screenshots (if appropriate)

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist

My code follows the code style of this project
My change requires a change to the documentation
I have updated the documentation accordingly
I have read the README document
I have added tests to cover my changes
All new and existing tests passed

License

I confirm that this pull request can be released under the Apache 2 license

dscpinheiro · 2026-03-19T17:20:26Z

Screenshots on this PR would be helpful to understand what the pages will look like (you can get the artifacts from the doc updater step).

AlexDaines · 2026-03-19T19:32:45Z

Screenshots on this PR would be helpful to understand what the pages will look like (you can get the artifacts from the doc updater step).

Good idea. Added an example screenshot

muhammad-othman · 2026-03-20T15:49:12Z

I thought we will use <strong> tag or something to convey the importance of these paragraphs, adding Important: seems overly verbose.

Copilot

Pull request overview

Updates the SDK documentation generator’s XML-doc-to-HTML transformation so <important> and <note> tags render as the existing “noteblock” callout UI used elsewhere in the doc output.

Changes:

Add callout-element handling to map <important> / <note> into <div class="noteblock"> with a header label.
Emit a standardized <div class="noteheader">Important:</div> / Note: header inside those blocks.
Add unit tests verifying the generated HTML output for common and edge cases.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
generator/.DevConfigs/4638aac9-482b-475c-a414-a34014955753.json	Adds required dev config entry for a patch-level doc generator fix.
docgenerator/SDKDocGeneratorLib/NDocUtilities.cs	Implements the new `<important>` / `<note>` element-to-HTML transformation behavior.
docgenerator/SDKDocGenerator.UnitTests/NDocUtilitiesHtmlTests.cs	Adds unit tests covering callout rendering, nested markup, and attribute preservation.

Copilot · 2026-03-20T15:52:09Z

+        }
+
+        [Fact]
+        public void NoteTagWithTypeAttribute_DoesNotThrow()


PR description says "5 unit tests added" but this file contains 6 [Fact] tests (including this one). Please update the PR description/testing section to match the actual test additions.

Copilot · 2026-03-20T15:52:09Z

+                                // Write callout header after all attributes are written
+                                if (isCallout)
+                                {
+                                    writer.WriteRaw("<div class=\"noteheader\">" + calloutHeader + "</div>");


writer.WriteRaw("<div class=\"noteheader\">" + calloutHeader + "</div>") bypasses XmlWriter escaping and structure checks. Consider writing the header using WriteStartElement/WriteAttributeString/WriteString instead, so any future header text changes are safely escaped and the output remains well-formed.

Suggested change

writer.WriteRaw("<div class=\"noteheader\">" + calloutHeader + "</div>");

writer.WriteStartElement("div");

writer.WriteAttributeString("class", "noteheader");

writer.WriteString(calloutHeader);

writer.WriteEndElement();

Copilot · 2026-03-20T15:52:09Z

+        [Fact]
+        public void NoteTagWithTypeAttribute_DoesNotThrow()
+        {
+            var result = TransformSummary("<note type=\"caution\"><para>Be careful.</para></note>");
+
+            Assert.Equal(
+                "<p><div class=\"noteblock\" type=\"caution\"><div class=\"noteheader\">Note:</div><p>Be careful.</p></div></p>",
+                result);


The test name NoteTagWithTypeAttribute_DoesNotThrow is misleading because the test asserts exact rendered HTML, not just that no exception is thrown. Renaming it to reflect the expected rendering (e.g., that attributes are preserved) would make failures easier to interpret.

peterrsongg · 2026-03-20T16:06:51Z

I do kind of agree with Muhammad's general comment that the tag should wrap the text in bold using or something like that. Don't feel too strongly about keeping or removing "Important" but i think the text should be bolded at least

AlexDaines · 2026-03-20T21:07:22Z

I thought we will use tag or something to convey the importance of these paragraphs, adding Important: seems overly verbose.

I do kind of agree with Muhammad's general comment that the tag should wrap the text in bold using ** or something like that. Don't feel too strongly about keeping or removing "Important" but i think the text should be bolded at least**

I agree with this assessment. I went ahead and revised to use css changes to emphasize and sections and updated screenshots with the new implementation.

muhammad-othman

Added few other comments but they are suggestions and not blocking so I'm approving the PR anyway.

muhammad-othman · 2026-03-20T23:27:08Z

                                writer.WriteStartElement(elementName);

+                                // Add CSS class if the original element has a class mapping
+                                string cssClass;


nit: not need to define the class beforehand as it isn't used anywhere outside the if condition, you can do this instead

if (NdocToHtmlClassMapping.TryGetValue(originalLocalName, out var cssClass)) { writer.WriteAttributeString("class", cssClass); }

muhammad-othman · 2026-03-20T23:30:22Z

            { "see", "a" },
-            { "paramref", "code" }
+            { "paramref", "code" },
+            { "important", "div" },


I would prefer if we use another element for important other than div for better accessibility.

muhammad-othman · 2026-03-20T23:35:56Z

-            { "paramref", "code" }
+            { "paramref", "code" },
+            { "important", "div" },
+            { "note", "div" }


maybe we can even use small for note and if we did so we wont need NdocToHtmlClassMapping as important&note can be identified with html tags and no need for css classes.

AlexDaines force-pushed the adaines/important-tag-fix branch from 68460c4 to da80b4c Compare March 17, 2026 18:01

Render <important> and <note> XML doc tags as styled noteblock divs

6324c97

AlexDaines force-pushed the adaines/important-tag-fix branch from da80b4c to 6324c97 Compare March 18, 2026 18:03

AlexDaines marked this pull request as ready for review March 19, 2026 16:49

muhammad-othman requested review from muhammad-othman and peterrsongg March 19, 2026 17:29

muhammad-othman requested a review from Copilot March 20, 2026 15:48

Copilot started reviewing on behalf of muhammad-othman March 20, 2026 15:49 View session

Copilot AI reviewed Mar 20, 2026

View reviewed changes

Render <important> and <note> XML doc tags as styled noteblock divs

10506db

muhammad-othman approved these changes Mar 20, 2026

View reviewed changes

peterrsongg approved these changes Mar 20, 2026

View reviewed changes

AlexDaines merged commit 1ba8e23 into development Mar 23, 2026
11 checks passed

AlexDaines deleted the adaines/important-tag-fix branch March 23, 2026 15:22

AlexDaines mentioned this pull request Apr 1, 2026

fix: Render <list>, <item>, <term>, and <description> XML doc tags as… #4378

Merged

16 tasks

-                                    writer.WriteRaw("<div class=\"noteheader\">" + calloutHeader + "</div>");
+                                    writer.WriteStartElement("div");
+                                    writer.WriteAttributeString("class", "noteheader");
+                                    writer.WriteString(calloutHeader);
+                                    writer.WriteEndElement();

Conversation

AlexDaines commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and Context

Testing

Dry-run - Powershell5

Dry-run - Dotnet4

Screenshots (if appropriate)

Types of changes

Checklist

License

Uh oh!

dscpinheiro commented Mar 19, 2026

Uh oh!

AlexDaines commented Mar 19, 2026

Uh oh!

muhammad-othman commented Mar 20, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

peterrsongg commented Mar 20, 2026

Uh oh!

AlexDaines commented Mar 20, 2026

Uh oh!

muhammad-othman left a comment

Choose a reason for hiding this comment

Uh oh!

muhammad-othman Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

muhammad-othman Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

muhammad-othman Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

AlexDaines commented Mar 13, 2026 •

edited

Loading