Skip to content

Commit e90d38a

Browse files
authored
create include with original content from WN issue (#35418)
1 parent c7ffbdb commit e90d38a

File tree

1 file changed

+28
-0
lines changed

1 file changed

+28
-0
lines changed
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## Improvements to XML comment generator
2+
3+
<!-- https://github.com/dotnet/aspnetcore/pull/61145 -->
4+
5+
<!-- it should throw fewer build errors now.
6+
- It should also work with the Identity API XML comments but I haven't verified that.
7+
- Maybe update docs about failure mode. -->
8+
9+
The XML comment generator has been enhanced to better handle complex types. In conjunction, the generator now gracefully bypasses processing for complex types that previously caused build errors. Taken together, these changes improve the robustness of XML comment generation but change the failure mode for certain scenarios from build errors to missing metadata.
10+
11+
In addition, XML doc comment processing can now be configured to access XML comments in other assemblies. This is useful for generating documentation for types that are defined outside the current assembly, such as the `ProblemDetails` type in the `Microsoft.AspNetCore.Http` namespace.
12+
13+
This configuration is done with directives in the project build file. The following example shows how to configure the XML comment generator to access XML comments for types in the `Microsoft.AspNetCore.Http` assembly, which includes the `ProblemDetails` class.
14+
15+
```xml
16+
<Target Name="AddOpenApiDependencies" AfterTargets="ResolveReferences">
17+
<ItemGroup>
18+
<!-- Include XML documentation from Microsoft.AspNetCore.Http.Abstractions to get metadata for ProblemDetails -->
19+
<AdditionalFiles
20+
Include="@(ReferencePath->'%(RootDir)%(Directory)%(Filename).xml')"
21+
Condition="'%(ReferencePath.Filename)' == 'Microsoft.AspNetCore.Http.Abstractions'"
22+
KeepMetadata="Identity;HintPath" />
23+
</ItemGroup>
24+
</Target>
25+
```
26+
27+
We expect to include XML comments from a selected set of assemblies in the shared framework in future previews, to avoid the need for this configuration in most cases.
28+
<!--[!INCLUDE[](~/release-notes/aspnetcore-10/includes/xml-comment-generation.md)] -->

0 commit comments

Comments
 (0)