Skip to content
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

Allow xml docs to still be created when 'emit metadata only' is on. #57667

Merged
merged 17 commits into from
Jan 21, 2022
Merged

Allow xml docs to still be created when 'emit metadata only' is on. #57667

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
5500a3f
Allow xml docs to still be created when 'emit metadata only' is on.
CyrusNajmabadi Nov 9, 2021
eb7d683
Add VB tests
CyrusNajmabadi Nov 10, 2021
5ebfb62
Simplify
CyrusNajmabadi Nov 10, 2021
1129003
Simplify
CyrusNajmabadi Nov 10, 2021
40296be
Update src/Compilers/Core/Portable/Compilation/Compilation.cs
CyrusNajmabadi Nov 10, 2021
96a8eae
Fix
CyrusNajmabadi Nov 10, 2021
7f56cb3
Merge branch 'metadataOnlyEmitXmlDocs' of https://github.com/CyrusNaj…
CyrusNajmabadi Nov 10, 2021
f6b9a4a
Remove parameter
CyrusNajmabadi Nov 16, 2021
3936ea4
Pass in doc mode explicitly
CyrusNajmabadi Nov 16, 2021
4748c69
Actually show the full xml docs we get
CyrusNajmabadi Nov 16, 2021
fac24f8
Update src/Compilers/CSharp/Test/Emit/Emit/CompilationEmitTests.cs
CyrusNajmabadi Jan 20, 2022
22e5e4b
Update src/Compilers/CSharp/Test/Emit/Emit/CompilationEmitTests.cs
CyrusNajmabadi Jan 20, 2022
30493b1
Update src/Compilers/CSharp/Test/Emit/Emit/CompilationEmitTests.cs
CyrusNajmabadi Jan 20, 2022
7d3c4b1
Update src/Compilers/CSharp/Test/Emit/Emit/CompilationEmitTests.cs
CyrusNajmabadi Jan 20, 2022
27ede16
Merge remote-tracking branch 'upstream/main' into metadataOnlyEmitXml…
CyrusNajmabadi Jan 20, 2022
5a24f14
Merge branch 'metadataOnlyEmitXmlDocs' of https://github.com/CyrusNaj…
CyrusNajmabadi Jan 20, 2022
c4591e9
Normalize whitespace
CyrusNajmabadi Jan 20, 2022
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
18 changes: 11 additions & 7 deletions src/Compilers/CSharp/Portable/Compilation/CSharpCompilation.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3274,15 +3274,15 @@ private void GenerateModuleInitializer(PEModuleBuilder moduleBeingBuilt, Diagnos
}
}

internal override bool GenerateResourcesAndDocumentationComments(
internal override bool GenerateResources(
CommonPEModuleBuilder moduleBuilder,
Stream? xmlDocStream,
Stream? win32Resources,
bool useRawWin32Resources,
string? outputNameOverride,
DiagnosticBag diagnostics,
CancellationToken cancellationToken)
{
cancellationToken.ThrowIfCancellationRequested();

// Use a temporary bag so we don't have to refilter pre-existing diagnostics.
DiagnosticBag? resourceDiagnostics = DiagnosticBag.GetInstance();

Expand All @@ -3294,11 +3294,15 @@ internal override bool GenerateResourcesAndDocumentationComments(
AddedModulesResourceNames(resourceDiagnostics),
resourceDiagnostics);

if (!FilterAndAppendAndFreeDiagnostics(diagnostics, ref resourceDiagnostics, cancellationToken))
{
return false;
}
return FilterAndAppendAndFreeDiagnostics(diagnostics, ref resourceDiagnostics, cancellationToken);
}

internal override bool GenerateDocumentationComments(
Stream? xmlDocStream,
string? outputNameOverride,
DiagnosticBag diagnostics,
CancellationToken cancellationToken)
{
cancellationToken.ThrowIfCancellationRequested();

// Use a temporary bag so we don't have to refilter pre-existing diagnostics.
Expand Down
305 changes: 304 additions & 1 deletion src/Compilers/CSharp/Test/Emit/Emit/CompilationEmitTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
using System.Reflection.Metadata;
using System.Reflection.Metadata.Ecma335;
using System.Reflection.PortableExecutable;
using System.Text;
using System.Threading;
using Microsoft.CodeAnalysis.CSharp.Emit;
using Microsoft.CodeAnalysis.CSharp.Symbols;
Expand Down Expand Up @@ -178,7 +179,6 @@ namespace N.;
Diagnostic(ErrorCode.WRN_UnassignedInternalField, "field").WithArguments("N.X.field", "null").WithLocation(4, 21));
}

// Check that EmitMetadataOnly works
[Fact]
public void EmitMetadataOnly()
{
Expand Down Expand Up @@ -246,6 +246,309 @@ public static void Main()
}
}

[Fact]
public void EmitMetadataOnly_XmlDocs_NoDocMode_Success()
CyrusNajmabadi marked this conversation as resolved.
Show resolved Hide resolved
{
CSharpCompilation comp = CreateCompilation(@"
namespace Goo.Bar
{
/// <summary>This should be emitted</summary>
public class Test1
{
public static void SayHello()
{
Console.WriteLine(""hello"");
}
}
}
", assemblyName: "test", parseOptions: CSharpParseOptions.Default.WithDocumentationMode(DocumentationMode.None));

EmitResult emitResult;
byte[] mdOnlyImage;
byte[] xmlDocBytes;

using (var peStream = new MemoryStream())
using (var xmlStream = new MemoryStream())
{
emitResult = comp.Emit(peStream, xmlDocumentationStream: xmlStream, options: new EmitOptions(metadataOnly: true));
mdOnlyImage = peStream.ToArray();
xmlDocBytes = xmlStream.ToArray();
}

Assert.True(emitResult.Success);
emitResult.Diagnostics.Verify();
Assert.True(mdOnlyImage.Length > 0, "no metadata emitted");
Assert.Equal(
@"<?xml version=""1.0""?>
<doc>
<assembly>
<name>test</name>
</assembly>
<members>
</members>
</doc>
",
Encoding.UTF8.GetString(xmlDocBytes));
}

[Fact]
public void EmitMetadataOnly_XmlDocs_NoDocMode_SyntaxWarning()
{
CSharpCompilation comp = CreateCompilation(@"
namespace Goo.Bar
{
/// <summary>This should still emit
public class Test1
{
public static void SayHello()
{
Console.WriteLine(""hello"");
}
}
}
", assemblyName: "test", parseOptions: CSharpParseOptions.Default.WithDocumentationMode(DocumentationMode.None));

EmitResult emitResult;
byte[] mdOnlyImage;
byte[] xmlDocBytes;

using (var peStream = new MemoryStream())
using (var xmlStream = new MemoryStream())
{
emitResult = comp.Emit(peStream, xmlDocumentationStream: xmlStream, options: new EmitOptions(metadataOnly: true));
mdOnlyImage = peStream.ToArray();
xmlDocBytes = xmlStream.ToArray();
}

Assert.True(emitResult.Success);
emitResult.Diagnostics.Verify();

Assert.True(mdOnlyImage.Length > 0, "no metadata emitted");
Assert.Equal(
@"<?xml version=""1.0""?>
<doc>
<assembly>
<name>test</name>
</assembly>
<members>
</members>
</doc>
",
Encoding.UTF8.GetString(xmlDocBytes));
}

[Fact]
public void EmitMetadataOnly_XmlDocs_DiagnoseDocMode_SyntaxWarning()
{
CSharpCompilation comp = CreateCompilation(@"
namespace Goo.Bar
{
/// <summary>This should still emit
public class Test1
{
public static void SayHello()
{
Console.WriteLine(""hello"");
}
}
}
", assemblyName: "test", parseOptions: CSharpParseOptions.Default.WithDocumentationMode(DocumentationMode.Diagnose));

EmitResult emitResult;
byte[] mdOnlyImage;
byte[] xmlDocBytes;

using (var peStream = new MemoryStream())
using (var xmlStream = new MemoryStream())
{
emitResult = comp.Emit(peStream, xmlDocumentationStream: xmlStream, options: new EmitOptions(metadataOnly: true));
mdOnlyImage = peStream.ToArray();
xmlDocBytes = xmlStream.ToArray();
}

// This should not fail the emit (as it's a warning).
Assert.True(emitResult.Success);
emitResult.Diagnostics.Verify(
// (5,1): warning CS1570: XML comment has badly formed XML -- 'Expected an end tag for element 'summary'.'
// public class Test1
Diagnostic(ErrorCode.WRN_XMLParseError, "").WithArguments("summary").WithLocation(5, 1),
// (7,28): warning CS1591: Missing XML comment for publicly visible type or member 'Test1.SayHello()'
// public static void SayHello()
Diagnostic(ErrorCode.WRN_MissingXMLComment, "SayHello").WithArguments("Goo.Bar.Test1.SayHello()").WithLocation(7, 28));

Assert.True(mdOnlyImage.Length > 0, "no metadata emitted");
Assert.Equal(
@"<?xml version=""1.0""?>
<doc>
<assembly>
<name>test</name>
</assembly>
<members>
<!-- Badly formed XML comment ignored for member ""T:Goo.Bar.Test1"" -->
</members>
</doc>
",
Encoding.UTF8.GetString(xmlDocBytes));
}

[Fact]
public void EmitMetadataOnly_XmlDocs_DiagnoseDocMode_SemanticWarning()
{
CSharpCompilation comp = CreateCompilation(@"
namespace Goo.Bar
{
/// <summary><see cref=""T""/></summary>
public class Test1
{
public static void SayHello()
{
Console.WriteLine(""hello"");
}
}
}
", assemblyName: "test", parseOptions: CSharpParseOptions.Default.WithDocumentationMode(DocumentationMode.Diagnose));

EmitResult emitResult;
byte[] mdOnlyImage;
byte[] xmlDocBytes;

using (var peStream = new MemoryStream())
using (var xmlStream = new MemoryStream())
{
emitResult = comp.Emit(peStream, xmlDocumentationStream: xmlStream, options: new EmitOptions(metadataOnly: true));
mdOnlyImage = peStream.ToArray();
xmlDocBytes = xmlStream.ToArray();
}

// This should not fail the emit (as it's a warning).
Assert.True(emitResult.Success);
emitResult.Diagnostics.Verify(
// (4,29): warning CS1574: XML comment has cref attribute 'T' that could not be resolved
// /// <summary><see cref="T"/></summary>
Diagnostic(ErrorCode.WRN_BadXMLRef, "T").WithArguments("T").WithLocation(4, 29),
// (7,28): warning CS1591: Missing XML comment for publicly visible type or member 'Test1.SayHello()'
// public static void SayHello()
Diagnostic(ErrorCode.WRN_MissingXMLComment, "SayHello").WithArguments("Goo.Bar.Test1.SayHello()").WithLocation(7, 28));

Assert.True(mdOnlyImage.Length > 0, "no metadata emitted");
Assert.Equal(
@"<?xml version=""1.0""?>
<doc>
<assembly>
<name>test</name>
</assembly>
<members>
<member name=""T:Goo.Bar.Test1"">
<summary><see cref=""!:T""/></summary>
</member>
</members>
</doc>
",
Encoding.UTF8.GetString(xmlDocBytes));
}

[Fact]
public void EmitMetadataOnly_XmlDocs_DiagnoseDocMode_Success()
{
CSharpCompilation comp = CreateCompilation(@"
namespace Goo.Bar
{
/// <summary>This should emit</summary>
public class Test1
{
public static void SayHello()
{
Console.WriteLine(""hello"");
}
}
}
", assemblyName: "test", parseOptions: CSharpParseOptions.Default.WithDocumentationMode(DocumentationMode.Diagnose));

EmitResult emitResult;
byte[] mdOnlyImage;
byte[] xmlDocBytes;

using (var peStream = new MemoryStream())
using (var xmlStream = new MemoryStream())
{
emitResult = comp.Emit(peStream, xmlDocumentationStream: xmlStream, options: new EmitOptions(metadataOnly: true));
mdOnlyImage = peStream.ToArray();
xmlDocBytes = xmlStream.ToArray();
}

// This should not fail the emit (as it's a warning).
Assert.True(emitResult.Success);
emitResult.Diagnostics.Verify(
// (7,28): warning CS1591: Missing XML comment for publicly visible type or member 'Test1.SayHello()'
// public static void SayHello()
Diagnostic(ErrorCode.WRN_MissingXMLComment, "SayHello").WithArguments("Goo.Bar.Test1.SayHello()").WithLocation(7, 28));

Assert.True(mdOnlyImage.Length > 0, "no metadata emitted");
Assert.Equal(
@"<?xml version=""1.0""?>
<doc>
<assembly>
<name>test</name>
</assembly>
<members>
<member name=""T:Goo.Bar.Test1"">
<summary>This should emit</summary>
</member>
</members>
</doc>
",
Encoding.UTF8.GetString(xmlDocBytes));
}

[Fact]
public void EmitMetadataOnly_XmlDocs_ParseDocMode_Success()
{
CSharpCompilation comp = CreateCompilation(@"
namespace Goo.Bar
{
/// <summary>This should emit</summary>
public class Test1
{
public static void SayHello()
{
Console.WriteLine(""hello"");
}
}
}
", assemblyName: "test", parseOptions: CSharpParseOptions.Default.WithDocumentationMode(DocumentationMode.Parse));

EmitResult emitResult;
byte[] mdOnlyImage;
byte[] xmlDocBytes;

using (var peStream = new MemoryStream())
using (var xmlStream = new MemoryStream())
{
emitResult = comp.Emit(peStream, xmlDocumentationStream: xmlStream, options: new EmitOptions(metadataOnly: true));
mdOnlyImage = peStream.ToArray();
xmlDocBytes = xmlStream.ToArray();
}

Assert.True(emitResult.Success);
emitResult.Diagnostics.Verify();

Assert.True(mdOnlyImage.Length > 0, "no metadata emitted");
Assert.Equal(
@"<?xml version=""1.0""?>
<doc>
<assembly>
<name>test</name>
</assembly>
<members>
<member name=""T:Goo.Bar.Test1"">
<summary>This should emit</summary>
</member>
</members>
</doc>
",
Encoding.UTF8.GetString(xmlDocBytes));
}

[Fact]
public void EmitRefAssembly_PrivateMain()
{
Expand Down
11 changes: 3 additions & 8 deletions src/Compilers/Core/Portable/CommandLine/CommonCompiler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1259,14 +1259,9 @@ private void CompileAndEmit(
return;
}

success = compilation.GenerateResourcesAndDocumentationComments(
moduleBeingBuilt,
xmlStreamDisposerOpt?.Stream,
win32ResourceStreamOpt,
useRawWin32Resources: false,
emitOptions.OutputNameOverride,
diagnostics,
cancellationToken);
success =
compilation.GenerateResources(moduleBeingBuilt, win32ResourceStreamOpt, useRawWin32Resources: false, diagnostics, cancellationToken) &&
compilation.GenerateDocumentationComments(xmlStreamDisposerOpt?.Stream, emitOptions.OutputNameOverride, diagnostics, cancellationToken);
}
}

Expand Down
Loading