HttpClient.Dispose documentation says it is invoked by Finalize but the code does not support this statement

[dmeeze]

https://github.com/dotnet/dotnet-api-docs/blame/main/xml/System.Net.Http/HttpClient.xml#L922

None of the implementations I can find in Framework or Core support this statement. As far as I can see there are no explicit finalizers in the code at all.

https://github.com/microsoft/referencesource/blob/master/System/net/System/Net/Http/HttpClient.cs

The statement may well have once been true (I can't find out when that might have been) but it doesn't look like it's true today.

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

Issue Details

---

https://github.com/dotnet/dotnet-api-docs/blame/main/xml/System.Net.Http/HttpClient.xml#L922

None of the implementations I can find in Framework or Core support this statement. As far as I can see there are no explicit finalizers in the code at all.

https://github.com/microsoft/referencesource/blob/master/System/net/System/Net/Http/HttpClient.cs

The statement may well have once been true (I can't find out when that might have been) but it doesn't look like it's true today.

Author:	dmeeze
Assignees:	-
Labels:	area-System.Net, untriaged, Pri3
Milestone:	-

[rzikm]

@dotnet/docs Looks like there is a standard text used for Dispose(bool) remark. The HttpClient class is not the only class which does not have an explicit finalizer (UdpClient is an example of another one and there are others outside of networking area). Do you have a suggestion how to update the text so that we can update all occurences at once?

[gewarren]

I think it's fine to just remove the bits about the finalizer where it doesn't apply. The text doesn't have to be consistent for all Dispose(bool) methods. Otherwise, we could reword it something like this:

This method is called by the public Dispose() method (and the xref:System.Object.Finalize%2A method, if it exists). Dispose() invokes the protected Dispose(Boolean) method with the disposing parameter set to true. xref:System.Object.Finalize%2A, if it exists, invokes Dispose with disposing set to false.

But again, I think it's better to remove the finalizer comments in the appropriate places.

[antonfirsov]

@gewarren in my understanding, the Dispose(bool) method exists (1) to enable the introduction of a finalizer in future versions, (2) let derived classes/class hierarchies introduce a finalizer -- which then may end up calling Dispose(false) of the base class(es) even if the original classes do not define a finalizer. Because of this, I believe we should not remove the finalizer comment, and it would be wiser to update the standard text across all our Dispose(bool) docs with the if it exists remark.