Skip to content

Flatten anonymous nested struct/union fields (#408) #1721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jevansaks merged 6 commits into from
Jun 12, 2026
Merged

Flatten anonymous nested struct/union fields (#408) #1721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5225d3e
Flatten anonymous nested struct/union fields (#408)
JeremyKuhne Jun 11, 2026
713faf0
Add tests for flattened anonymous struct accessors (#408)
JeremyKuhne Jun 11, 2026
79267ce
Add no-op and skip-reinterpreted tests for anonymous flattening (#408)
JeremyKuhne Jun 11, 2026
ff071b7
Add tests guarding against over-flattening of nested struct values
JeremyKuhne Jun 11, 2026
3026878
Enable anonymous-type flattening by default and fix two codegen bugs …
JeremyKuhne Jun 11, 2026
a0e936d
Fix CS8151 for flattened accessors in the source-generator path
JeremyKuhne Jun 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
281 changes: 147 additions & 134 deletions src/Microsoft.Windows.CsWin32/Generator.ApiDocs.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,111 @@ public partial class Generator
{
internal Docs? ApiDocs { get; }

private static void EmitLine(StringBuilder stringBuilder, string yamlDocSrc)
{
stringBuilder.Append(yamlDocSrc.Trim());
}

private static void EmitDoc(string yamlDocSrc, StringBuilder docCommentsBuilder, ApiDetails? docs, string docsAnchor)
{
if (yamlDocSrc.Contains('\n'))
{
docCommentsBuilder.AppendLine();
var docReader = new StringReader(yamlDocSrc);
string? paramDocLine;

bool inParagraph = false;
bool inComment = false;
int blankLineCounter = 0;
while ((paramDocLine = docReader.ReadLine()) is object)
{
if (string.IsNullOrWhiteSpace(paramDocLine))
{
if (++blankLineCounter >= 2 && inParagraph)
{
docCommentsBuilder.AppendLine("</para>");
inParagraph = false;
inComment = false;
}

continue;
}
else if (blankLineCounter > 0)
{
blankLineCounter = 0;
}
else if (docCommentsBuilder.Length > 0 && docCommentsBuilder[docCommentsBuilder.Length - 1] != '\n')
{
docCommentsBuilder.Append(' ');
}

if (inParagraph)
{
if (docCommentsBuilder.Length > 0 && docCommentsBuilder[docCommentsBuilder.Length - 1] is not (' ' or '\n'))
{
docCommentsBuilder.Append(' ');
}
}
else
{
docCommentsBuilder.Append("/// <para>");
inParagraph = true;
inComment = true;
}

if (!inComment)
{
docCommentsBuilder.Append("/// ");
}

if (paramDocLine.IndexOf("<table", StringComparison.OrdinalIgnoreCase) >= 0 ||
paramDocLine.IndexOf("<img", StringComparison.OrdinalIgnoreCase) >= 0 ||
paramDocLine.IndexOf("<ul", StringComparison.OrdinalIgnoreCase) >= 0 ||
paramDocLine.IndexOf("<ol", StringComparison.OrdinalIgnoreCase) >= 0 ||
paramDocLine.IndexOf("```", StringComparison.OrdinalIgnoreCase) >= 0 ||
paramDocLine.IndexOf("<<", StringComparison.OrdinalIgnoreCase) >= 0)
{
// We don't try to format tables, so truncate at this point.
if (inParagraph)
{
docCommentsBuilder.AppendLine("</para>");
inParagraph = false;
inComment = false;
}

docCommentsBuilder.AppendLine($@"/// <para>This doc was truncated.</para>");

break; // is this the right way?
}

EmitLine(docCommentsBuilder, paramDocLine);
}

if (inParagraph)
{
if (!inComment)
{
docCommentsBuilder.Append("/// ");
}

docCommentsBuilder.AppendLine("</para>");
inParagraph = false;
inComment = false;
}

if (docs is object)
{
docCommentsBuilder.AppendLine($@"/// <para><see href=""{docs.HelpLink}#{docsAnchor}"">Read more on learn.microsoft.com</see>.</para>");
}

docCommentsBuilder.Append("/// ");
}
else
{
EmitLine(docCommentsBuilder, yamlDocSrc);
}
}

private T AddApiDocumentation<T>(string api, T memberDeclaration)
where T : MemberDeclarationSyntax
{
Expand Down Expand Up @@ -41,50 +146,7 @@ private T AddApiDocumentation<T>(string api, T memberDeclaration)

if (docs.Fields is object)
{
var fieldsDocBuilder = new StringBuilder();
switch (memberDeclaration)
{
case StructDeclarationSyntax structDeclaration:
memberDeclaration = memberDeclaration.ReplaceNodes(
structDeclaration.Members.OfType<FieldDeclarationSyntax>(),
(_, field) =>
{
VariableDeclaratorSyntax? variable = field.Declaration.Variables.Single();
if (docs.Fields.TryGetValue(variable.Identifier.ValueText, out string? fieldDoc))
{
fieldsDocBuilder.Append("/// <summary>");
EmitDoc(fieldDoc, fieldsDocBuilder, docs, "members");
fieldsDocBuilder.AppendLine("</summary>");
if (field.Declaration.Type.HasAnnotations(OriginalDelegateAnnotation))
{
fieldsDocBuilder.AppendLine(@$"/// <remarks>See the <see cref=""{field.Declaration.Type.GetAnnotations(OriginalDelegateAnnotation).Single().Data}"" /> delegate for more about this function.</remarks>");
}

field = field.WithLeadingTrivia(ParseLeadingTrivia(fieldsDocBuilder.ToString().Replace("\r\n", "\n")));
fieldsDocBuilder.Clear();
}

return field;
});
break;
case EnumDeclarationSyntax enumDeclaration:
memberDeclaration = memberDeclaration.ReplaceNodes(
enumDeclaration.Members,
(_, field) =>
{
if (docs.Fields.TryGetValue(field.Identifier.ValueText, out string? fieldDoc))
{
fieldsDocBuilder.Append($@"/// <summary>");
EmitDoc(fieldDoc, fieldsDocBuilder, docs, "members");
fieldsDocBuilder.AppendLine("</summary>");
field = field.WithLeadingTrivia(ParseLeadingTrivia(fieldsDocBuilder.ToString().Replace("\r\n", "\n")));
fieldsDocBuilder.Clear();
}

return field;
});
break;
}
memberDeclaration = this.ApplyFieldDocs(memberDeclaration, docs);
}

if (docs.ReturnValue is object)
Expand Down Expand Up @@ -116,110 +178,61 @@ private T AddApiDocumentation<T>(string api, T memberDeclaration)
}

return memberDeclaration;
}

static void EmitLine(StringBuilder stringBuilder, string yamlDocSrc)
private T ApplyFieldDocs<T>(T memberDeclaration, ApiDetails docs)
where T : MemberDeclarationSyntax
{
if (docs.Fields is null)
{
stringBuilder.Append(yamlDocSrc.Trim());
return memberDeclaration;
}

static void EmitDoc(string yamlDocSrc, StringBuilder docCommentsBuilder, ApiDetails? docs, string docsAnchor)
var fieldsDocBuilder = new StringBuilder();
switch (memberDeclaration)
{
if (yamlDocSrc.Contains('\n'))
{
docCommentsBuilder.AppendLine();
var docReader = new StringReader(yamlDocSrc);
string? paramDocLine;

bool inParagraph = false;
bool inComment = false;
int blankLineCounter = 0;
while ((paramDocLine = docReader.ReadLine()) is object)
{
if (string.IsNullOrWhiteSpace(paramDocLine))
case StructDeclarationSyntax structDeclaration:
memberDeclaration = memberDeclaration.ReplaceNodes(
structDeclaration.Members.OfType<FieldDeclarationSyntax>(),
(_, field) =>
{
if (++blankLineCounter >= 2 && inParagraph)
VariableDeclaratorSyntax? variable = field.Declaration.Variables.Single();
if (docs.Fields.TryGetValue(variable.Identifier.ValueText, out string? fieldDoc))
{
docCommentsBuilder.AppendLine("</para>");
inParagraph = false;
inComment = false;
}

continue;
}
else if (blankLineCounter > 0)
{
blankLineCounter = 0;
}
else if (docCommentsBuilder.Length > 0 && docCommentsBuilder[docCommentsBuilder.Length - 1] != '\n')
{
docCommentsBuilder.Append(' ');
}
fieldsDocBuilder.Append("/// <summary>");
EmitDoc(fieldDoc, fieldsDocBuilder, docs, "members");
fieldsDocBuilder.AppendLine("</summary>");
if (field.Declaration.Type.HasAnnotations(OriginalDelegateAnnotation))
{
fieldsDocBuilder.AppendLine(@$"/// <remarks>See the <see cref=""{field.Declaration.Type.GetAnnotations(OriginalDelegateAnnotation).Single().Data}"" /> delegate for more about this function.</remarks>");
}

if (inParagraph)
{
if (docCommentsBuilder.Length > 0 && docCommentsBuilder[docCommentsBuilder.Length - 1] is not (' ' or '\n'))
{
docCommentsBuilder.Append(' ');
field = field.WithLeadingTrivia(ParseLeadingTrivia(fieldsDocBuilder.ToString().Replace("\r\n", "\n")));
fieldsDocBuilder.Clear();
}
}
else
{
docCommentsBuilder.Append("/// <para>");
inParagraph = true;
inComment = true;
}

if (!inComment)
return field;
});
break;
case EnumDeclarationSyntax enumDeclaration:
memberDeclaration = memberDeclaration.ReplaceNodes(
enumDeclaration.Members,
(_, field) =>
{
docCommentsBuilder.Append("/// ");
}

if (paramDocLine.IndexOf("<table", StringComparison.OrdinalIgnoreCase) >= 0 ||
paramDocLine.IndexOf("<img", StringComparison.OrdinalIgnoreCase) >= 0 ||
paramDocLine.IndexOf("<ul", StringComparison.OrdinalIgnoreCase) >= 0 ||
paramDocLine.IndexOf("<ol", StringComparison.OrdinalIgnoreCase) >= 0 ||
paramDocLine.IndexOf("```", StringComparison.OrdinalIgnoreCase) >= 0 ||
paramDocLine.IndexOf("<<", StringComparison.OrdinalIgnoreCase) >= 0)
{
// We don't try to format tables, so truncate at this point.
if (inParagraph)
if (docs.Fields.TryGetValue(field.Identifier.ValueText, out string? fieldDoc))
{
docCommentsBuilder.AppendLine("</para>");
inParagraph = false;
inComment = false;
fieldsDocBuilder.Append($@"/// <summary>");
EmitDoc(fieldDoc, fieldsDocBuilder, docs, "members");
fieldsDocBuilder.AppendLine("</summary>");
field = field.WithLeadingTrivia(ParseLeadingTrivia(fieldsDocBuilder.ToString().Replace("\r\n", "\n")));
fieldsDocBuilder.Clear();
}

docCommentsBuilder.AppendLine($@"/// <para>This doc was truncated.</para>");

break; // is this the right way?
}

EmitLine(docCommentsBuilder, paramDocLine);
}

if (inParagraph)
{
if (!inComment)
{
docCommentsBuilder.Append("/// ");
}

docCommentsBuilder.AppendLine("</para>");
inParagraph = false;
inComment = false;
}

if (docs is object)
{
docCommentsBuilder.AppendLine($@"/// <para><see href=""{docs.HelpLink}#{docsAnchor}"">Read more on learn.microsoft.com</see>.</para>");
}

docCommentsBuilder.Append("/// ");
}
else
{
EmitLine(docCommentsBuilder, yamlDocSrc);
}
return field;
});
break;
}

return memberDeclaration;
}
}
Loading
Loading