Skip to content

Commit

Permalink
XML Documentation Fix - Batch #2 (#2834)
Browse files Browse the repository at this point in the history 
* Batch #2

* Reverting removal of the snippet files.

* Fixing build break caused by parameter not having a comment.

* These changes should fix the broken comments
  • Loading branch information
@benrr101
benrr101 authored Sep 12, 2024
1 parent b1d3a82 commit 764add3
Show file tree
Hide file tree
Showing 13 changed files with 6,972 additions and 2,880 deletions.
2 changes: 1 addition & 1 deletion doc/samples/SqlBatch_ExecuteReader.cs
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// <Snippet1>
// <Snippet1>
using Microsoft.Data.SqlClient;

class Program
Expand Down
129 changes: 99 additions & 30 deletions doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,89 @@
<?xml version="1.0"?>
<docs>
<docs>
<members name="SqlBatchCommand">
<SqlBatchCommand>
<summary>
SqlBatchCommand allows for the execution of multiple SQL commands in a SqlBatch.
</summary>
SqlBatchCommand allows for the execution of multiple SQL commands in a SqlBatch.
</summary>
</SqlBatchCommand>
<ctor1>
<summary>Initializes a new <see cref="SqlBatchCommand"/>.</summary>
<remarks>
<format type="text/markdown">
<![CDATA[
## Examples
The following example creates a <xref:Microsoft.Data.SqlClient.SqlConnection> and a SqlBatch, then adds multiple <xref:Microsoft.Data.SqlClient.SqlBatchCommand> objects to the batch. It then executes the batch, creating a <xref:Microsoft.Data.SqlClient.SqlDataReader>. The example reads through the results of the batch commands, writing them to the console. Finally, the example closes the <xref:Microsoft.Data.SqlClient.SqlDataReader> and then the <xref:Microsoft.Data.SqlClient.SqlConnection> as the `using` blocks fall out of scope.
<summary>
Initializes a new <see cref="T:SqlBatchCommand" />.
</summary>
<example>
The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> and a SqlBatch, then adds multiple <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> objects to the batch. It then executes the batch, creating a <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> . The example reads through the results of the batch commands, writing them to the console. Finally, the example closes the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> and then the <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> as the <c>using</c> blocks fall out of scope.
<code language="c#">
using Microsoft.Data.SqlClient;

class Program
{
static void Main()
{
string str = "Data Source=(local);Initial Catalog=Northwind;"
+ "Integrated Security=SSPI;Encrypt=False";
RunBatch(str);
}

static void RunBatch(string connString)
{
using var connection = new SqlConnection(connString);
connection.Open();

var batch = new SqlBatch(connection);

const int count = 10;
const string parameterName = "parameter";
for (int i = 0; i &lt; count; i++)
{
var batchCommand = new SqlBatchCommand($"SELECT @{parameterName} as value");
batchCommand.Parameters.Add(new SqlParameter(parameterName, i));
batch.BatchCommands.Add(batchCommand);
}

// Optionally Prepare
batch.Prepare();

[!code-csharp[SqlCommand Example#1](~/../sqlclient/doc/samples/SqlBatch_ExecuteReader.cs#1)]
]]>
</format>
</remarks>
var results = new List&lt;int&gt;(count);
using (SqlDataReader reader = batch.ExecuteReader())
{
do
{
while (reader.Read())
{
results.Add(reader.GetFieldValue&lt;int&gt;(0));
}
} while (reader.NextResult());
}
Console.WriteLine(string.Join(", ", results));
}
}

</code>
</example>
</ctor1>
<ctor2>
<summary>Initializes a new <see cref="SqlBatchCommand"/>.</summary>
<param name="commandText">The text of the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand"/>.</param>
<param name="commandType">Indicates how the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CommandText"/> property is to be interpreted.</param>
<param name="parameters">A collection of <see cref="T:Microsoft.Data.SqlClient.SqlParameter"/> objects is used to create the <see cref="T:Microsoft.Data.SqlClient.SqlParameterCollection"/>.</param>
<param name="columnEncryptionSetting">The encryption setting. For more information, see [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine).</param>
<summary>
Initializes a new <see cref="T:SqlBatchCommand" />.
</summary>
<param name="commandText">
The text of the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" />.
</param>
<param name="commandType">
Indicates how the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CommandText" /> property is to be interpreted.
</param>
<param name="parameters">
A collection of <see cref="T:Microsoft.Data.SqlClient.SqlParameter" /> objects is used to create the <see cref="T:Microsoft.Data.SqlClient.SqlParameterCollection" />.
</param>
<param name="columnEncryptionSetting">
The encryption setting. For more information, see <see href="/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted</see>.
</param>
</ctor2>
<Parameters>
<summary>Gets the <see cref="T:Microsoft.Data.SqlClient.SqlParameterCollection"/>.</summary>
<value>The parameters of the Transact-SQL statement or stored procedure. The default is an empty collection.</value>
<summary>
Gets the <see cref="T:Microsoft.Data.SqlClient.SqlParameterCollection" />.
</summary>
<value>
The parameters of the Transact-SQL statement or stored procedure. The default is an empty collection.
</value>
</Parameters>
<CommandBehavior>
<summary>
Expand All @@ -38,28 +93,42 @@ The following example creates a <xref:Microsoft.Data.SqlClient.SqlConnection> an
<ColumnEncryptionSetting>
<summary>
Not currently implemented.
The encryption setting. For more information, see [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine).
The encryption setting. For more information, see <see href="/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted</see>.
</summary>
</ColumnEncryptionSetting>
<CreateParameter>
<summary>Creates a new instance of a <see cref="T:Microsoft.Data.SqlClient.SqlParameter"/> object.</summary>
<summary>
Creates a new instance of a <see cref="T:Microsoft.Data.SqlClient.SqlParameter" /> object.
</summary>
</CreateParameter>
<CanCreateParameter>
<summary>
Returns whether the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CreateParameter"/> method is implemented.
Returns whether the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CreateParameter" /> method is implemented.
</summary>
</CanCreateParameter>
<CommandText>
<summary>Gets or sets the text command to run against the data source.</summary>
<value>The text command to execute. The default value is an empty string ("").</value>
<summary>
Gets or sets the text command to run against the data source.
</summary>
<value>
The text command to execute. The default value is an empty string ("").
</value>
</CommandText>
<CommandType>
<summary>Gets or sets how the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CommandText" /> property is interpreted.</summary>
<value>One of the enumeration values that specifies how a command string is interpreted. The default is <see langword="Text" />.</value>
<summary>
Gets or sets how the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CommandText" /> property is interpreted.
</summary>
<value>
One of the enumeration values that specifies how a command string is interpreted. The default is <see cref="F:System.Data.CommandType.Text" />.
</value>
</CommandType>
<DbParameterCollection>
<summary>Gets the collection of <see cref="T:Microsoft.Data.SqlClient.SqlParameter" /> objects.</summary>
<value>The parameters of the SQL statement or stored procedure.</value>
<summary>
Gets the collection of <see cref="T:Microsoft.Data.SqlClient.SqlParameter" /> objects.
</summary>
<value>
The parameters of the SQL statement or stored procedure.
</value>
</DbParameterCollection>
<RecordsAffected>
<summary>
Expand Down
91 changes: 49 additions & 42 deletions doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml
View file
Original file line number Diff line number Diff line change
@@ -1,37 +1,27 @@
<?xml version="1.0"?>
<docs>
<docs>
<members name="SqlBatchCommandCollection">
<SqlBatchCommandCollection>
<summary>
A collection of instances of
<see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" />, contained within a
<see cref="T:Microsoft.Data.SqlClient.SqlBatch" />.
A collection of instances of <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" />, contained within a <see cref="T:Microsoft.Data.SqlClient.SqlBatch" />.
</summary>
</SqlBatchCommandCollection>
<Add1>
<summary>
Add a
<see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> to the end of the
<see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.
Add a <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> to the end of the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.
</summary>
<value></value>
</Add1>
<Add2>
<param name="item">
The object to add to the <see cref="T:System.Collections.Generic.ICollection`1" />.
</param>
<summary>
Adds the specified <see cref="T:System.Data.Common.DbBatchCommand" /> object to the <see cref="T:System.Collections.Generic.ICollection`1" />.
</summary>
<remarks>To be added.</remarks>
</summary>
</Add2>
<Contains1>
<summary>
Determines whether a
<see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> is in the
<see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.
Determines whether a <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> is in the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.
</summary>
<value></value>
</Contains1>
<Contains2>
<param name="item">
Expand All @@ -43,13 +33,11 @@
<returns>
<see langword="true" /> if the <see cref="T:System.Data.Common.DbBatchCommand" /> is in the collection; otherwise <see langword="false" />.
</returns>
<remarks>To be added.</remarks>
</Contains2>
<CopyTo1>
<summary>
Copies the entire <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" /> to a one dimensional array, starting at the target index of the target array.
</summary>
<value></value>
</CopyTo1>
<CopyTo2>
<param name="array">
Expand All @@ -61,7 +49,6 @@
<summary>
Copies the elements of the <see cref="T:System.Collections.Generic.ICollection`1" /> to an <see cref="T:System.Array" />, starting at a particular <see cref="T:System.Array" /> index.
</summary>
<remarks>To be added.</remarks>
</CopyTo2>
<IndexOf1>
<summary>
Expand All @@ -81,13 +68,11 @@
<returns>
The index of the specified <see cref="T:System.Data.Common.DbBatchCommand" /> object.
</returns>
<remarks>To be added.</remarks>
</IndexOf2>
</IndexOf2>
<Insert1>
<summary>
Inserts an item into the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" /> at the specified index.
</summary>
<exception cref="T:System.ArgumentOutOfRangeException"></exception>
</Insert1>
<Insert2>
<param name="index">
Expand All @@ -99,7 +84,6 @@
<summary>
Inserts the specified index of the <see cref="T:System.Data.Common.DbBatchCommand" /> object with the specified name into the collection at the specified index.
</summary>
<remarks>To be added.</remarks>
</Insert2>
<Remove1>
<summary>
Expand All @@ -111,25 +95,30 @@
</Remove1>
<Remove2>
<param name="item">
The object to remove from the <see cref="T:System.Collections.Generic.ICollection`1" />.
The object to remove from the <see cref="T:System.Collections.Generic.ICollection`1" /> .
</param>
<summary>
Removes the specified <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object from the collection.
</summary>
<returns>
<see langword="true" /> if <paramref name="item" /> was successfully removed; otherwise, <see langword="false" />. This method also returns <see langword="false" /> if <paramref name="item" /> was not found in the <see cref="T:System.Collections.Generic.ICollection`1" />.
</returns>
<remarks>To be added.</remarks>
</returns>
</Remove2>
<this1>
<summary>Gets or Sets the element at the specified index.</summary>
<returns>The element at the specified index.</returns>
<exception cref="T:System.ArgumentOutOfRangeException"></exception>
<summary>
Gets or Sets the element at the specified index.
</summary>
<returns>
The element at the specified index.
</returns>
</this1>
<this2>
<summary>Gets or Sets the element at the specified index.</summary>
<returns>The element at the specified index.</returns>
<exception cref="T:System.ArgumentOutOfRangeException"></exception>
<summary>
Gets or Sets the element at the specified index.
</summary>
<returns>
The element at the specified index.
</returns>
</this2>
<GetBatchCommand>
<param name="index">
Expand All @@ -146,31 +135,49 @@
<param name="index">
The index where the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object should be located.
</param>
<param name="batchCommand">To be added.</param>
<param name="batchCommand">
The <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object to add to the collection.
</param>
<summary>
Sets the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object at the specified index to a new value.
</summary>
<remarks>To be added.</remarks>
</SetBatchCommand>
<Count>
<summary>Gets the number of elements contained in the <see cref="T:System.Collections.Generic.ICollection`1" />.</summary>
<value>The number of elements contained in the <see cref="T:System.Collections.Generic.ICollection`1" />.</value>
<summary>
Gets the number of elements contained in the <see cref="T:System.Collections.Generic.ICollection`1" />.
</summary>
<value>
The number of elements contained in the <see cref="T:System.Collections.Generic.ICollection`1" />.
</value>
</Count>
<IsReadOnly>
<summary>Specifies whether the collection is read-only.</summary>
<summary>
Specifies whether the collection is read-only.
</summary>
<value>
<see langword="true" /> if the collection is read-only; otherwise <see langword="false" />.</value>
<see langword="true" /> if the collection is read-only; otherwise <see langword="false" />.
</value>
</IsReadOnly>
<GetEnumerator>
<summary>Returns the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object at the specified index in the collection.</summary>
<returns>The <see cref="T:System.Data.Common.DbBatchCommand" /> object at the specified index in the collection.</returns>
<summary>
Returns the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object at the specified index in the collection.
</summary>
<returns>
The <see cref="T:System.Data.Common.DbBatchCommand" /> object at the specified index in the collection.
</returns>
</GetEnumerator>
<Clear>
<summary>Removes all <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> values from the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.</summary>
<summary>
Removes all <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> values from the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.
</summary>
</Clear>
<RemoveAt>
<param name="index">The index where the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object is located.</param>
<summary>Removes the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object at the specified index from the collection.</summary>
<param name="index">
The index where the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object is located.
</param>
<summary>
Removes the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object at the specified index from the collection.
</summary>
</RemoveAt>
</members>
</docs>
Loading

0 comments on commit 764add3

Please sign in to comment.