Skip to content

Commit 6a9539f

Browse files
rojiroji
authored
API documentation for DbDataSource (dotnet#8311)
Closes dotnet/runtime#73722
1 parent 25621f2 commit 6a9539f

File tree

2 files changed

+159
-51
lines changed

2 files changed

+159
-51
lines changed

‎xml/System.Data.Common/DbDataSource.xml‎

Lines changed: 156 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@
2121
</Interface>
2222
</Interfaces>
2323
<Docs>
24-
<summary>To be added.</summary>
25-
<remarks>To be added.</remarks>
24+
<summary>Represents a data source which can be used to obtain open connections, and against which commands can be executed directly.</summary>
25+
<remarks>Unlike <see cref="T:System.Data.Common.DbProviderFactory" />, which is purely a factory for provider-specific objects such as <see cref="T:System.Data.Common.DbConnection" />, <see cref="T:System.Data.Common.DbDataSource" /> hands out open connections to specific databases, encapsulating all the information needed to connect to a database. Depending on how the <see cref="T:System.Data.Common.DbDataSource" /> was configured, the connections it hands out may be pooled.</remarks>
2626
</Docs>
2727
<Members>
2828
<Member MemberName=".ctor">
@@ -38,7 +38,7 @@
3838
</AssemblyInfo>
3939
<Parameters />
4040
<Docs>
41-
<summary>To be added.</summary>
41+
<summary>Initializes a new instance of the <see cref="T:System.Data.Common.DbDataSource" /> class.</summary>
4242
<remarks>To be added.</remarks>
4343
</Docs>
4444
</Member>
@@ -58,8 +58,8 @@
5858
<ReturnType>System.String</ReturnType>
5959
</ReturnValue>
6060
<Docs>
61-
<summary>To be added.</summary>
62-
<value>To be added.</value>
61+
<summary>Gets the connection string of the database represented by this <see cref="T:System.Data.Common.DbDataSource" />. The exact contents of the connection string depend on the specific data source for this connection.</summary>
62+
<value>The connection string of the database represented by this <see cref="T:System.Data.Common.DbDataSource" />. The exact contents of the connection string depend on the specific data source for this connection.</value>
6363
<remarks>To be added.</remarks>
6464
</Docs>
6565
</Member>
@@ -80,9 +80,18 @@
8080
</ReturnValue>
8181
<Parameters />
8282
<Docs>
83-
<summary>To be added.</summary>
84-
<returns>To be added.</returns>
85-
<remarks>To be added.</remarks>
83+
<summary>Returns a <see cref="T:System.Data.Common.DbBatch" /> that's ready for execution against the <see cref="T:System.Data.Common.DbDataSource" />.</summary>
84+
<returns>A <see cref="T:System.Data.Common.DbBatch" /> that's ready for execution against the <see cref="T:System.Data.Common.DbDataSource" />.</returns>
85+
<remarks>
86+
<format type="text/markdown"><![CDATA[
87+
88+
## Remarks
89+
Batches returned from this method are already configured to execute against their originating <xref:System.Data.Common.DbDataSource>; their <xref:System.Data.Common.DbBatch.Connection%2A> does not need to be set, and doing so will throw an exception.
90+
91+
Since these batches have no explicitly-managed connection, it is not possible to use them with transactions, and trying to set <xref:System.Data.Common.DbBatch.Transaction%2A> will throw an exception. To use a transaction, get a connection from <xref:System.Data.Common.DbDataSource.OpenConnection%2A> and create a command against it.
92+
93+
]]></format>
94+
</remarks>
8695
</Docs>
8796
</Member>
8897
<Member MemberName="CreateCommand">
@@ -103,10 +112,19 @@
103112
<Parameter Name="commandText" Type="System.String" />
104113
</Parameters>
105114
<Docs>
106-
<param name="commandText">To be added.</param>
107-
<summary>To be added.</summary>
108-
<returns>To be added.</returns>
109-
<remarks>To be added.</remarks>
115+
<param name="commandText">The text command with which to initialize the <see cref="T:System.Data.Common.DbCommand" /> that this method returns.</param>
116+
<summary>Returns a <see cref="T:System.Data.Common.DbCommand" /> that's ready for execution against the <see cref="T:System.Data.Common.DbDataSource" />.</summary>
117+
<returns>A <see cref="T:System.Data.Common.DbCommand" /> that's ready for execution against the <see cref="T:System.Data.Common.DbDataSource" />.</returns>
118+
<remarks>
119+
<format type="text/markdown"><![CDATA[
120+
121+
## Remarks
122+
Commands returned from this method are already configured to execute against their originating <xref:System.Data.Common.DbDataSource>; their <xref:System.Data.Common.DbCommand.Connection%2A> does not need to be set, and doing so will throw an exception.
123+
124+
Since these commands have no explicitly-managed connection, it is not possible to use them with transactions, and trying to set <xref:System.Data.Common.DbCommand.Transaction%2A> will throw an exception. To use a transaction, get a connection from <xref:System.Data.Common.DbDataSource.OpenConnection%2A> and create a command against it.
125+
126+
]]></format>
127+
</remarks>
110128
</Docs>
111129
</Member>
112130
<Member MemberName="CreateConnection">
@@ -126,9 +144,18 @@
126144
</ReturnValue>
127145
<Parameters />
128146
<Docs>
129-
<summary>To be added.</summary>
130-
<returns>To be added.</returns>
131-
<remarks>To be added.</remarks>
147+
<summary>Returns a <see cref="T:System.Data.Common.DbBatch" /> that's ready for execution against the <see cref="T:System.Data.Common.DbDataSource" />.</summary>
148+
<returns>A <see cref="T:System.Data.Common.DbBatch" /> that's ready for execution against the <see cref="T:System.Data.Common.DbDataSource" />.</returns>
149+
<remarks>
150+
<format type="text/markdown"><![CDATA[
151+
152+
## Remarks
153+
Batches returned from this method are already configured to execute against their originating <xref:System.Data.Common.DbDataSource>; their <xref:System.Data.Common.DbBatch.Connection%2A> does not need to be set, and doing so will throw an exception.
154+
155+
Since these batches have no explicitly-managed connection, it is not possible to use them with transactions, and trying to set <xref:System.Data.Common.DbBatch.Transaction%2A> will throw an exception.
156+
157+
]]></format>
158+
</remarks>
132159
</Docs>
133160
</Member>
134161
<Member MemberName="CreateDbBatch">
@@ -148,9 +175,16 @@
148175
</ReturnValue>
149176
<Parameters />
150177
<Docs>
151-
<summary>To be added.</summary>
152-
<returns>To be added.</returns>
153-
<remarks>To be added.</remarks>
178+
<summary>Returns a new, closed connection to the database represented by this <see cref="T:System.Data.Common.DbDataSource" />.</summary>
179+
<returns>A new, closed connection to the database represented by this <see cref="T:System.Data.Common.DbDataSource" />.</returns>
180+
<remarks>
181+
<format type="text/markdown"><![CDATA[
182+
183+
## Remarks
184+
This method is meant to be overridden by implementing ADO.NET providers, and is not a user-facing API.
185+
186+
]]></format>
187+
</remarks>
154188
</Docs>
155189
</Member>
156190
<Member MemberName="CreateDbCommand">
@@ -171,10 +205,17 @@
171205
<Parameter Name="commandText" Type="System.String" />
172206
</Parameters>
173207
<Docs>
174-
<param name="commandText">To be added.</param>
175-
<summary>To be added.</summary>
176-
<returns>To be added.</returns>
177-
<remarks>To be added.</remarks>
208+
<param name="commandText">The text command with which to initialize the <see cref="T:System.Data.Common.DbCommand" /> that this method returns.</param>
209+
<summary>Returns a <see cref="T:System.Data.Common.DbCommand" /> that's ready for execution against the <see cref="T:System.Data.Common.DbDataSource" />.</summary>
210+
<returns>A <see cref="T:System.Data.Common.DbCommand" /> that's ready for execution against the <see cref="T:System.Data.Common.DbDataSource" />.</returns>
211+
<remarks>
212+
<format type="text/markdown"><![CDATA[
213+
214+
## Remarks
215+
This method is meant to be overridden by implementing ADO.NET providers, and is not a user-facing API.
216+
217+
]]></format>
218+
</remarks>
178219
</Docs>
179220
</Member>
180221
<Member MemberName="CreateDbConnection">
@@ -194,9 +235,16 @@
194235
</ReturnValue>
195236
<Parameters />
196237
<Docs>
197-
<summary>To be added.</summary>
198-
<returns>To be added.</returns>
199-
<remarks>To be added.</remarks>
238+
<summary>Returns a <see cref="T:System.Data.Common.DbBatch" /> that's ready for execution against the <see cref="T:System.Data.Common.DbDataSource" />.</summary>
239+
<returns>A <see cref="T:System.Data.Common.DbBatch" /> that's ready for execution against the <see cref="T:System.Data.Common.DbDataSource" />.</returns>
240+
<remarks>
241+
<format type="text/markdown"><![CDATA[
242+
243+
## Remarks
244+
This method is meant to be overridden by implementing ADO.NET providers, and is not a user-facing API.
245+
246+
]]></format>
247+
</remarks>
200248
</Docs>
201249
</Member>
202250
<Member MemberName="Dispose">
@@ -219,8 +267,15 @@
219267
</ReturnValue>
220268
<Parameters />
221269
<Docs>
222-
<summary>Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.</summary>
223-
<remarks>To be added.</remarks>
270+
<summary>Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.</summary>
271+
<remarks>
272+
<format type="text/markdown"><![CDATA[
273+
274+
## Remarks
275+
If the current instance of <xref:System.Data.Common.DbDataSource> represents a connection pool, disposing it should close all idle connections, and arrange for busy connections to be closed as soon as possible.
276+
277+
]]></format>
278+
</remarks>
224279
</Docs>
225280
</Member>
226281
<Member MemberName="Dispose">
@@ -242,9 +297,16 @@
242297
<Parameter Name="disposing" Type="System.Boolean" />
243298
</Parameters>
244299
<Docs>
245-
<param name="disposing">To be added.</param>
246-
<summary>To be added.</summary>
247-
<remarks>To be added.</remarks>
300+
<param name="disposing"><see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.</param>
301+
<summary>Called by the Dispose() and Finalize() methods to release the managed and unmanaged resources used by the current instance of the <see cref="T:System.Data.Common.DbDataSource" /> class.</summary>
302+
<remarks>
303+
<format type="text/markdown"><![CDATA[
304+
305+
## Remarks
306+
This method is meant to be overridden by implementing ADO.NET providers, and is not a user-facing API.
307+
308+
]]></format>
309+
</remarks>
248310
</Docs>
249311
</Member>
250312
<Member MemberName="DisposeAsync">
@@ -269,7 +331,14 @@
269331
<Docs>
270332
<summary>Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.</summary>
271333
<returns>A task that represents the asynchronous dispose operation.</returns>
272-
<remarks>To be added.</remarks>
334+
<remarks>
335+
<format type="text/markdown"><![CDATA[
336+
337+
## Remarks
338+
If the current instance of <xref:System.Data.Common.DbDataSource> represents a connection pool, disposing it should close all idle connections, and arrange for busy connections to be closed as soon as possible.
339+
340+
]]></format>
341+
</remarks>
273342
</Docs>
274343
</Member>
275344
<Member MemberName="DisposeAsyncCore">
@@ -289,9 +358,16 @@
289358
</ReturnValue>
290359
<Parameters />
291360
<Docs>
292-
<summary>To be added.</summary>
293-
<returns>To be added.</returns>
294-
<remarks>To be added.</remarks>
361+
<summary>Performs application-defined tasks associated with freeing, releasing, or resetting managed resources asynchronously.</summary>
362+
<returns>A task that represents the asynchronous dispose operation.</returns>
363+
<remarks>
364+
<format type="text/markdown"><![CDATA[
365+
366+
## Remarks
367+
This method is meant to be overridden by implementing ADO.NET providers, and is not a user-facing API.
368+
369+
]]></format>
370+
</remarks>
295371
</Docs>
296372
</Member>
297373
<Member MemberName="OpenConnection">
@@ -311,9 +387,18 @@
311387
</ReturnValue>
312388
<Parameters />
313389
<Docs>
314-
<summary>To be added.</summary>
315-
<returns>To be added.</returns>
316-
<remarks>To be added.</remarks>
390+
<summary>Returns a new, open connection to the database represented by this <see cref="T:System.Data.Common.DbDataSource" />.</summary>
391+
<returns>A new, open connection to the database represented by this <see cref="T:System.Data.Common.DbDataSource" />.</returns>
392+
<remarks>
393+
<format type="text/markdown"><![CDATA[
394+
395+
## Remarks
396+
The returned connection is already open, and is ready for immediate use.
397+
398+
It is the responsibility of the caller to properly dispose the connection returned by this method. Failure to do so may result in a connection leak.
399+
400+
]]></format>
401+
</remarks>
317402
</Docs>
318403
</Member>
319404
<Member MemberName="OpenConnectionAsync">
@@ -334,10 +419,19 @@
334419
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
335420
</Parameters>
336421
<Docs>
337-
<param name="cancellationToken">To be added.</param>
338-
<summary>To be added.</summary>
339-
<returns>To be added.</returns>
340-
<remarks>To be added.</remarks>
422+
<param name="cancellationToken">A token to cancel the asynchronous operation.</param>
423+
<summary>Asynchronously returns a new, open connection to the database represented by this <see cref="T:System.Data.Common.DbDataSource" />.</summary>
424+
<returns>A new, open connection to the database represented by this <see cref="T:System.Data.Common.DbDataSource" />.</returns>
425+
<remarks>
426+
<format type="text/markdown"><![CDATA[
427+
428+
## Remarks
429+
The returned connection is already open, and is ready for immediate use.
430+
431+
It is the responsibility of the caller to properly dispose the connection returned by this method. Failure to do so may result in a connection leak.
432+
433+
]]></format>
434+
</remarks>
341435
</Docs>
342436
</Member>
343437
<Member MemberName="OpenDbConnection">
@@ -357,9 +451,16 @@
357451
</ReturnValue>
358452
<Parameters />
359453
<Docs>
360-
<summary>To be added.</summary>
361-
<returns>To be added.</returns>
362-
<remarks>To be added.</remarks>
454+
<summary>Returns a new, open connection to the database represented by this <see cref="T:System.Data.Common.DbDataSource" />.</summary>
455+
<returns>A new, open connection to the database represented by this <see cref="T:System.Data.Common.DbDataSource" />.</returns>
456+
<remarks>
457+
<format type="text/markdown"><![CDATA[
458+
459+
## Remarks
460+
This method is meant to be overridden by implementing ADO.NET providers, and is not a user-facing API.
461+
462+
]]></format>
463+
</remarks>
363464
</Docs>
364465
</Member>
365466
<Member MemberName="OpenDbConnectionAsync">
@@ -380,10 +481,17 @@
380481
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
381482
</Parameters>
382483
<Docs>
383-
<param name="cancellationToken">To be added.</param>
384-
<summary>To be added.</summary>
385-
<returns>To be added.</returns>
386-
<remarks>To be added.</remarks>
484+
<param name="cancellationToken">A token to cancel the asynchronous operation.</param>
485+
<summary>Asynchronously returns a new, open connection to the database represented by this <see cref="T:System.Data.Common.DbDataSource" />.</summary>
486+
<returns>A new, open connection to the database represented by this <see cref="T:System.Data.Common.DbDataSource" />.</returns>
487+
<remarks>
488+
<format type="text/markdown"><![CDATA[
489+
490+
## Remarks
491+
This method is meant to be overridden by implementing ADO.NET providers, and is not a user-facing API.
492+
493+
]]></format>
494+
</remarks>
387495
</Docs>
388496
</Member>
389497
</Members>

‎xml/System.Data.Common/DbProviderFactory.xml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -525,9 +525,9 @@ This property returns `false` by default; providers that implement <xref:System.
525525
<Parameter Name="connectionString" Type="System.String" Index="0" FrameworkAlternate="net-7.0" />
526526
</Parameters>
527527
<Docs>
528-
<param name="connectionString">To be added.</param>
529-
<summary>To be added.</summary>
530-
<returns>To be added.</returns>
528+
<param name="connectionString">The connection string of the database to be represented by this <see cref="T:System.Data.Common.DbDataSource" />. The exact contents of the connection string depend on the specific data source for this connection.</param>
529+
<summary>Returns a new instance of the provider's class that implements the <see cref="T:System.Data.Common.DbDataSource" /> class, representing the database for the given connection string and ready to hand out connections to it.</summary>
530+
<returns>A new instance of <see cref="T:System.Data.Common.DbDataSource" />.</returns>
531531
<remarks>To be added.</remarks>
532532
</Docs>
533533
</Member>

0 commit comments

Comments
 (0)