Skip to content

Fix up boilerplate text for Dispose/Finalize #8474

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
merged 12 commits into from
Oct 7, 2022
Merged

Fix up boilerplate text for Dispose/Finalize #8474

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
3a00b3f
fix up boilerplate text for dispose/finalize
gewarren Oct 7, 2022
c4d14ba
remove parentheses
gewarren Oct 7, 2022
6a00695
readd opening space to make diffing easier
gewarren Oct 7, 2022
7caefc7
delete extra line to make diffing easier
gewarren Oct 7, 2022
ccdb860
revert some componentmodel replacements
gewarren Oct 7, 2022
28e3d34
reversions
gewarren Oct 7, 2022
b1c496f
reset unrelated changes
gewarren Oct 7, 2022
bc7f0f3
reset
gewarren Oct 7, 2022
46fb955
couple more
gewarren Oct 7, 2022
b1c3af0
fix link
gewarren Oct 7, 2022
0bd6359
fix duplicate word
gewarren Oct 7, 2022
f78cc0d
slight wording improvements
gewarren Oct 7, 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
4 changes: 2 additions & 2 deletions xml/System.CodeDom.Compiler/TempFileCollection.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -552,8 +552,8 @@
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.
Copy link
Member

@stephentoub stephentoub Oct 10, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This remark isn't generic boilerplate but is actually the text on the TempFileCollection page. We know whether TempFileCollection implements a finalizer (it does). Seems like it would make sense to specialize this with that knowledge? Same for the rest of the occurrences here where we know whether it does or doesn't implement a finalizer.

Copy link
Contributor

@antonfirsov antonfirsov Oct 12, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So you mean specializing this general text in both cases? (when finalizer is overridden VS when it's missing)

What if we change the implementation (delete or add a finalizer)? Are we sure we have the processes, the awareness and the capacity to always ensure the necessary documentation change? Also, I would find a specialized text confusing, in case the finalizer is missing. Dispose(false) is never invoked from the built-in hierarchy, that case only makes sense if a subclass overrides the finalizer. We would need to properly explain this in the text.

IMO the boilerplate text is a safer option if we are not sure if we can (or want to) address these concerns.

When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this <xref:System.CodeDom.Compiler.TempFileCollection> references. This method invokes the `Dispose()` method of each referenced object.
Expand Down
2 changes: 1 addition & 1 deletion xml/System.ComponentModel.Design.Serialization/SerializationStore.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is true, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Design.Serialization.SerializationStore> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel.Design/ComponentDesigner.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -326,8 +326,8 @@
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is true, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Design.ComponentDesigner> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel.Design/DesignSurface.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -752,8 +752,8 @@

> [!NOTE]
> Because <xref:System.ComponentModel.Design.DesignSurface> does not have any native code to clean up, it does not have a finalizer that calls <xref:System.ComponentModel.Design.DesignSurface.Dispose%2A>. If you need to call <xref:System.ComponentModel.Design.DesignSurface.Dispose%2A>, you must add a finalizer yourself.
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.

This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is true, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Design.DesignSurface> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel.Design/DesignSurfaceManager.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -515,8 +515,8 @@

> [!NOTE]
> Because <xref:System.ComponentModel.Design.DesignSurfaceManager> does not have any native code to clean up, it does not have a finalizer that calls <xref:System.ComponentModel.Design.DesignSurfaceManager.Dispose%2A>. If you need to call <xref:System.ComponentModel.Design.DesignSurfaceManager.Dispose%2A>, you must add a finalizer yourself.
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.

This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is true, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Design.DesignSurfaceManager> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel.Design/DesignerActionService.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -483,8 +483,8 @@
- Removes the current service from the list of available services in the design environment through a call to the <xref:System.ComponentModel.Design.IServiceContainer.RemoveService%2A> method.

- Unsubscribes to component change events from the associated <xref:System.ComponentModel.Design.IComponentChangeService> interface.
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.

This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Design.DesignerActionService> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel.Design/DesignerTransaction.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -497,8 +497,8 @@ using (host.CreateTransaction() {
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Design.DesignerTransaction> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel.Design/InheritanceService.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,8 +261,8 @@
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is true, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Design.InheritanceService> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel.Design/LocalizationExtenderProvider.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -220,8 +220,8 @@
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is true, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Design.LocalizationExtenderProvider> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel.Design/MenuCommandService.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,8 +279,8 @@
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is true, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Design.MenuCommandService> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel.Design/ServiceContainer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -600,8 +600,8 @@

## Remarks
<xref:System.ComponentModel.Design.ServiceContainer.Dispose%2A> walks all instantiated services within the container and disposes any that implement <xref:System.IDisposable>, and clears the service list.
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.

This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is true, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Design.ServiceContainer> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel/Component.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -420,8 +420,8 @@
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public <xref:System.ComponentModel.Component.Dispose%2A> method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
## Remarks
This method is called by the public <xref:System.ComponentModel.Component.Dispose> method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Component> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel/Container.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -449,8 +449,8 @@
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public `Dispose` method and the <xref:System.Object.Finalize%2A> method. `Dispose` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is true, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.Container> references. This method invokes the `Dispose` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel/MarshalByValueComponent.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -358,8 +358,8 @@
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is true, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.MarshalByValueComponent> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
4 changes: 2 additions & 2 deletions xml/System.ComponentModel/NestedContainer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,8 +221,8 @@
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize%2A> method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
## Remarks
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is true, this method releases all resources held by any managed objects that this <xref:System.ComponentModel.NestedContainer> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
2 changes: 1 addition & 1 deletion xml/System.Data.Common/DataAdapter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -515,7 +515,7 @@
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public <xref:System.IDisposable.Dispose%2A> method and the <xref:System.Object.Finalize%2A> method. `Dispose` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. <xref:System.Object.Finalize%2A> invokes `Dispose` with `disposing` set to `false`.
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this <xref:System.Data.Common.DataAdapter> references. This method invokes the `Dispose` method of each referenced object.

Expand Down
8 changes: 4 additions & 4 deletions xml/System.Data.Common/DbCommandBuilder.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -386,18 +386,18 @@
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public <xref:System.Data.Common.DbCommandBuilder.Dispose%2A> method and the `Finalize` method. <xref:System.Data.Common.DbCommandBuilder.Dispose%2A> invokes the protected <xref:System.Data.Common.DbCommandBuilder.Dispose%2A> method with the disposing parameter set to `true`. `Finalize` invokes `Dispose` with `disposing` set to `false`.
## Remarks
This method is called by the public <xref:System.Data.Common.DbCommandBuilder.Dispose%2A> method and the <xref:System.Object.Finalize> method, if it has been overridden. <xref:System.Data.Common.DbCommandBuilder.Dispose%2A> invokes the protected <xref:System.Data.Common.DbCommandBuilder.Dispose%2A> method with the disposing parameter set to `true`. `Finalize` specifies the `disposing` parameter as `false`.

When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this <xref:System.Data.Common.DbCommandBuilder> references. This method invokes the <xref:System.Data.Common.DbCommandBuilder.Dispose%2A> method of each referenced object.
When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this <xref:System.Data.Common.DbCommandBuilder> references. This method invokes the <xref:System.Data.Common.DbCommandBuilder.Dispose%2A> method of each referenced object.

]]></format>
</remarks>
<block subset="none" type="overrides">
<para>
<see cref="Overload:System.Data.Common.DbCommandBuilder.Dispose" /> can be called multiple times by other objects. When overriding <see cref="M:System.Data.Common.DbCommandBuilder.Dispose(System.Boolean)" />, be careful not to reference objects that have been previously disposed of in an earlier call to <see cref="Overload:System.Data.Common.DbCommandBuilder.Dispose" />. For more information about how to implement <see cref="M:System.Data.Common.DbCommandBuilder.Dispose(System.Boolean)" />, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose).

For more information about <see langword="Dispose" /> and <see langword="Finalize" />, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Overriding the Finalize Method](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)).</para>
For more information about <see langword="Dispose" /> and <see langword="Finalize" />, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Overriding the Finalize Method](/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)).</para>
</block>
<related type="Article" href="/dotnet/framework/data/adonet/generating-commands-with-commandbuilders">Generating Commands with CommandBuilders</related>
<related type="Article" href="/dotnet/framework/data/adonet/ado-net-overview">ADO.NET Overview</related>
Expand Down
2 changes: 1 addition & 1 deletion xml/System.Diagnostics.Tracing/EventSource.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -694,7 +694,7 @@ The following example shows an implementation of <xref:System.Diagnostics.Tracin
<format type="text/markdown"><![CDATA[

## Remarks
This method is called by the public `Dispose()` method and the `Finalize` method. `Dispose()` invokes the protected `Dispose(Boolean)` method with the `disposing` parameter set to `true`. `Finalize` invokes `Dispose` with `disposing` set to `false`.
This method is called by the public `Dispose()` method and the <xref:System.Object.Finalize> method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`.

When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this <xref:System.Diagnostics.Tracing.EventSource> references. This method invokes the `Dispose()` method of each referenced object.

Expand Down
Loading