search

dotnet / dotnet-api-docs

.NET API reference documentation (.NET 5+, .NET Core, .NET Framework)
https://docs.microsoft.com/dotnet/api/
Other
737 stars 1.57k forks source link

Public API document doesn't reflect the actual type of parameter #8219

Open gaufung opened 3 years ago

gaufung commented 3 years ago

This bunch of public APIs first parameter is LoggerFilterOptions instead of the ILoggingBuilder . And the return type is LoggerFilterOptions instead of ILoggingBuilder as well.

Suggestion 

-  /// <param name="builder">The <see cref="ILoggingBuilder"/> to add the filter to.</param>
+ /// <param name="builder">The <see cref="LoggerFilterOptions"/> to add the filter to.</param>

- /// <returns>The <see cref="ILoggingBuilder"/> so that additional calls can be chained.</returns>
+ /// <returns>The <see cref="LoggerFilterOptions"/> so that additional calls can be chained.</returns>
ghost commented 3 years ago

Tagging subscribers to this area: @maryamariyan See info in area-owners.md if you want to be subscribed.

Issue Details
This bunch of [public APIs](https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.Extensions.Logging/src/FilterLoggingBuilderExtensions.cs#L118-L189 ) first parameter is `LoggerFilterOptions` instead of the `ILoggingBuilder` . Suggestion ```diff - /// The to add the filter to. + /// The to add the filter to. ```
Author: gaufung
Assignees: -
Labels: `untriaged`, `area-Extensions-Logging`
Milestone: -
ericstj commented 3 years ago

@carlossanlop @maryamariyan do we need to do anything special to ensure this gets updated here too? https://github.com/dotnet/dotnet-api-docs/blob/2238750cc696339f0a8f04c786f7fe03b14e51ec/xml/Microsoft.Extensions.Logging/FilterLoggingBuilderExtensions.xml#L152

carlossanlop commented 3 years ago

The DocsPortingTool can't port API docs to elements that are already documented, so they need to get updated manually in the dotnet-api-docs xml.

maryamariyan commented 3 years ago

Thanks @carlossanlop

@gaufung would you be open to contributing over https://github.com/dotnet/dotnet-api-docs/blob/2238750cc696339f0a8f04c786f7fe03b14e51ec/xml/Microsoft.Extensions.Logging/FilterLoggingBuilderExtensions.xml#L152 on the dotnet/dotnet-api-docs repo to submit this edit over there?

ericstj commented 3 years ago

I think this missed the cut-off for 6.0 docs, moving to 7.0. @carlossanlop, suppose we just flip this library to have it's source as the source-of-truth for docs, would we sill need to port anything?