Skip to content

Commit aec18be

Browse files
wforneywforney
committed
Enhance XML documentation in extension methods
Added XML documentation comments to methods in ArrayExtensions.cs, DataRowExtensions.cs, and DataTableExtensions.cs to improve code readability and provide better context for users. Method implementations remain unchanged, with minor formatting improvements for consistency.
1 parent 0ed8f84 commit aec18be

File tree

3 files changed

+172
-171
lines changed

3 files changed

+172
-171
lines changed

‎SharedCode.Core/Collections/ArrayExtensions.cs‎

Lines changed: 77 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,91 @@
11
using System.ComponentModel;
22

33
namespace SharedCode.Collections;
4+
45
/// <summary>
56
/// The array extensions class
67
/// </summary>
78
public static class ArrayExtensions
89
{
9-
/// <summary>
10-
/// Converts an Array of arbitrary type to an array of type T. If a suitable converter cannot be
11-
/// found to do the conversion, a NotSupportedException is thrown.
12-
/// </summary>
13-
/// <typeparam name="T">The type of items in the output array.</typeparam>
14-
/// <param name="this">The input array.</param>
15-
/// <returns>The new array.</returns>
16-
/// <exception cref="NotSupportedException">
17-
/// A suitable converter cannot be found to do the conversion.
18-
/// </exception>
19-
/// <exception cref="ArgumentNullException">input</exception>
20-
public static T?[] ConvertTo<T>(this Array @this)
21-
{
22-
_ = @this ?? throw new ArgumentNullException(nameof(@this));
23-
Contract.Ensures(Contract.Result<T[]>() is not null);
10+
/// <summary>
11+
/// Converts an Array of arbitrary type to an array of type T. If a suitable converter cannot be
12+
/// found to do the conversion, a NotSupportedException is thrown.
13+
/// </summary>
14+
/// <typeparam name="T">The type of items in the output array.</typeparam>
15+
/// <param name="this">The input array.</param>
16+
/// <returns>The new array.</returns>
17+
/// <exception cref="NotSupportedException">
18+
/// A suitable converter cannot be found to do the conversion.
19+
/// </exception>
20+
/// <exception cref="ArgumentNullException">input</exception>
21+
public static T?[] ConvertTo<T>(this Array @this)
22+
{
23+
_ = @this ?? throw new ArgumentNullException(nameof(@this));
24+
Contract.Ensures(Contract.Result<T[]>() is not null);
2425

25-
var result = new T?[@this.Length];
26-
var tc = TypeDescriptor.GetConverter(typeof(T));
27-
var type = @this.GetValue(0)?.GetType() ?? @this.GetType().GetElementType() ?? typeof(object);
28-
if (tc.CanConvertFrom(type))
29-
{
30-
for (var i = 0; i < @this.Length; i++)
31-
{
32-
var value = @this.GetValue(i);
33-
result[i] = (T?)(value is null ? null : tc.ConvertFrom(value));
34-
}
35-
}
36-
else
37-
{
38-
tc = TypeDescriptor.GetConverter(type);
39-
if (tc.CanConvertTo(typeof(T)))
40-
{
41-
for (var i = 0; i < @this.Length; i++)
42-
{
43-
result[i] = (T?)tc.ConvertTo(@this.GetValue(i), typeof(T));
44-
}
45-
}
46-
else
47-
{
48-
throw new NotSupportedException("A suitable converter cannot be found to do the conversion.");
49-
}
50-
}
26+
var result = new T?[@this.Length];
27+
var tc = TypeDescriptor.GetConverter(typeof(T));
28+
var type = @this.GetValue(0)?.GetType() ?? @this.GetType().GetElementType() ?? typeof(object);
29+
if (tc.CanConvertFrom(type))
30+
{
31+
for (var i = 0; i < @this.Length; i++)
32+
{
33+
var value = @this.GetValue(i);
34+
result[i] = (T?)(value is null ? null : tc.ConvertFrom(value));
35+
}
36+
}
37+
else
38+
{
39+
tc = TypeDescriptor.GetConverter(type);
40+
if (tc.CanConvertTo(typeof(T)))
41+
{
42+
for (var i = 0; i < @this.Length; i++)
43+
{
44+
result[i] = (T?)tc.ConvertTo(@this.GetValue(i), typeof(T));
45+
}
46+
}
47+
else
48+
{
49+
throw new NotSupportedException("A suitable converter cannot be found to do the conversion.");
50+
}
51+
}
5152

52-
return result;
53-
}
53+
return result;
54+
}
5455

55-
/// <summary>
56-
/// Converts an array of any type to <see cref="List{T}" /> passing a mapping delegate
57-
/// Func{object, T} that returns type T. If T is null, it will not be added to the collection.
58-
/// If the array is null, then a new instance of <see cref="List{T}" /> is returned.
59-
/// </summary>
60-
/// <typeparam name="T">The type of the items in the output list.</typeparam>
61-
/// <param name="this">The array of items.</param>
62-
/// <param name="mapFunction">The map function.</param>
63-
/// <returns>The output list.</returns>
64-
public static IList<T> ToList<T>(this Array @this, Func<object, T> mapFunction)
65-
{
66-
Contract.Ensures(Contract.Result<List<T>>() is not null);
56+
/// <summary>
57+
/// Converts an array of any type to <see cref="List{T}"/> passing a mapping delegate
58+
/// Func{object, T} that returns type T. If T is null, it will not be added to the collection.
59+
/// If the array is null, then a new instance of <see cref="List{T}"/> is returned.
60+
/// </summary>
61+
/// <typeparam name="T">The type of the items in the output list.</typeparam>
62+
/// <param name="this">The array of items.</param>
63+
/// <param name="mapFunction">The map function.</param>
64+
/// <returns>The output list.</returns>
65+
public static IList<T> ToList<T>(this Array @this, Func<object, T> mapFunction)
66+
{
67+
Contract.Ensures(Contract.Result<List<T>>() is not null);
6768

68-
if (@this is null || mapFunction is null)
69-
{
70-
return new List<T>();
71-
}
69+
if (@this is null || mapFunction is null)
70+
{
71+
return [];
72+
}
7273

73-
var coll = new List<T>();
74-
for (var i = 0; i < @this.Length; i++)
75-
{
76-
var handler = mapFunction;
77-
if (handler is not null)
78-
{
79-
var arg = @this.GetValue(i);
80-
var val = arg is null ? default : handler(arg);
81-
if (val is not null)
82-
{
83-
coll.Add(val);
84-
}
85-
}
86-
}
74+
var coll = new List<T>();
75+
for (var i = 0; i < @this.Length; i++)
76+
{
77+
var handler = mapFunction;
78+
if (handler is not null)
79+
{
80+
var arg = @this.GetValue(i);
81+
var val = arg is null ? default : handler(arg);
82+
if (val is not null)
83+
{
84+
coll.Add(val);
85+
}
86+
}
87+
}
8788

88-
return coll;
89-
}
90-
}
89+
return coll;
90+
}
91+
}

‎SharedCode.Core/Data/DataRowExtensions.cs‎

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,30 @@
1-

2-
using System.Data;
1+
using System.Data;
32

43
namespace SharedCode.Data;
4+
55
/// <summary>
66
/// The data row extensions class
77
/// </summary>
88
public static class DataRowExtensions
99
{
10-
/// <summary>
11-
/// Creates a cloned and detached copy of a DataRow instance
12-
/// </summary>
13-
/// <typeparam name="T">The type of the DataRow if strongly typed</typeparam>
14-
/// <param name="this">The data row.</param>
15-
/// <param name="parentTable">The parent table.</param>
16-
/// <returns>An instance of the new DataRow</returns>
17-
/// <exception cref="ArgumentNullException">dataRow</exception>
18-
/// <exception cref="ArgumentNullException">parentTable</exception>
19-
public static T Clone<T>(this DataRow @this, DataTable parentTable)
20-
where T : DataRow
21-
{
22-
_ = @this ?? throw new ArgumentNullException(nameof(@this));
23-
_ = parentTable ?? throw new ArgumentNullException(nameof(parentTable));
24-
Contract.Ensures(Contract.Result<T>() is not null);
10+
/// <summary>
11+
/// Creates a cloned and detached copy of a DataRow instance
12+
/// </summary>
13+
/// <typeparam name="T">The type of the DataRow if strongly typed</typeparam>
14+
/// <param name="this">The data row.</param>
15+
/// <param name="parentTable">The parent table.</param>
16+
/// <returns>An instance of the new DataRow</returns>
17+
/// <exception cref="ArgumentNullException">dataRow</exception>
18+
/// <exception cref="ArgumentNullException">parentTable</exception>
19+
public static T Clone<T>(this DataRow @this, DataTable parentTable)
20+
where T : DataRow
21+
{
22+
_ = @this ?? throw new ArgumentNullException(nameof(@this));
23+
_ = parentTable ?? throw new ArgumentNullException(nameof(parentTable));
24+
Contract.Ensures(Contract.Result<T>() is not null);
2525

26-
var result = (T)parentTable.NewRow();
27-
result.ItemArray = @this.ItemArray;
28-
return result;
29-
}
26+
var result = (T)parentTable.NewRow();
27+
result.ItemArray = @this.ItemArray;
28+
return result;
29+
}
3030
}

‎SharedCode.Core/Data/DataTableExtensions.cs‎

Lines changed: 74 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -8,94 +8,94 @@ namespace SharedCode.Data;
88
/// </summary>
99
public static class DataTableExtensions
1010
{
11-
/// <summary>
12-
/// Converts a data table to a delimited string.
13-
/// </summary>
14-
/// <param name="this">The data table.</param>
15-
/// <param name="delimiter">The column delimiter.</param>
16-
/// <param name="includeHeader">if set to <c>true</c> [include header].</param>
17-
/// <exception cref="ArgumentNullException">table</exception>
18-
[SuppressMessage("Refactoring", "GCop659:Use 'var' instead of explicit type.", Justification = "The compiler does not infer DataColumn properly here so we have to use the type instead of var.")]
19-
public static string ToDelimitedString(this DataTable @this, string delimiter, bool includeHeader)
20-
{
21-
_ = @this ?? throw new ArgumentNullException(nameof(@this));
22-
Contract.Ensures(Contract.Result<string>() is not null);
11+
/// <summary>
12+
/// Converts a data table to a delimited string.
13+
/// </summary>
14+
/// <param name="this">The data table.</param>
15+
/// <param name="delimiter">The column delimiter.</param>
16+
/// <param name="includeHeader">if set to <c>true</c> [include header].</param>
17+
/// <exception cref="ArgumentNullException">table</exception>
18+
[SuppressMessage("Refactoring", "GCop659:Use 'var' instead of explicit type.", Justification = "The compiler does not infer DataColumn properly here so we have to use the type instead of var.")]
19+
public static string ToDelimitedString(this DataTable @this, string delimiter, bool includeHeader)
20+
{
21+
_ = @this ?? throw new ArgumentNullException(nameof(@this));
22+
Contract.Ensures(Contract.Result<string>() is not null);
2323

24-
var result = new StringBuilder();
24+
var result = new StringBuilder();
2525

26-
_ = result.Append(string.Empty);
26+
_ = result.Append(string.Empty);
2727

28-
if (includeHeader)
29-
{
30-
foreach (DataColumn column in @this.Columns)
31-
{
32-
_ = result.Append(column.ColumnName).Append(delimiter);
33-
}
28+
if (includeHeader)
29+
{
30+
foreach (DataColumn column in @this.Columns)
31+
{
32+
_ = result.Append(column.ColumnName).Append(delimiter);
33+
}
3434

35-
_ = result.Remove(--result.Length, 0).Append(Environment.NewLine);
36-
}
35+
_ = result.Remove(--result.Length, 0).Append(Environment.NewLine);
36+
}
3737

38-
foreach (DataRow row in @this.Rows)
39-
{
40-
foreach (var item in row.ItemArray)
41-
{
42-
if (item is DBNull)
43-
{
44-
_ = result.Append(delimiter);
45-
}
46-
else
47-
{
48-
// Double up all embedded double quotes To keep things simple, always delimit
49-
// with double-quotes so we don't have to determine in which cases they're
50-
// necessary and which cases they're not.
38+
foreach (DataRow row in @this.Rows)
39+
{
40+
foreach (var item in row.ItemArray)
41+
{
42+
if (item is DBNull)
43+
{
44+
_ = result.Append(delimiter);
45+
}
46+
else
47+
{
48+
// Double up all embedded double quotes To keep things simple, always delimit
49+
// with double-quotes so we don't have to determine in which cases they're
50+
// necessary and which cases they're not.
5151
#if NETSTANDARD2_1_OR_GREATER || NET6_0_OR_GREATER
52-
_ = result.Append('"').Append(item?.ToString()?.Replace("\"", "\"\"", StringComparison.Ordinal)).Append('"').Append(delimiter);
52+
_ = result.Append('"').Append(item?.ToString()?.Replace("\"", "\"\"", StringComparison.Ordinal)).Append('"').Append(delimiter);
5353
#else
54-
_ = result.Append('"').Append(item?.ToString()?.Replace("\"", "\"\"")).Append('"').Append(delimiter);
54+
_ = result.Append('"').Append(item?.ToString()?.Replace("\"", "\"\"")).Append('"').Append(delimiter);
5555
#endif
56-
}
57-
}
56+
}
57+
}
5858

59-
_ = result
60-
.Remove(result.Length - 1, 1)
61-
.Append(Environment.NewLine);
62-
}
59+
_ = result
60+
.Remove(result.Length - 1, 1)
61+
.Append(Environment.NewLine);
62+
}
6363

64-
return result.ToString();
65-
}
64+
return result.ToString();
65+
}
6666

67-
/// <summary>
68-
/// Converts the data table to XML.
69-
/// </summary>
70-
/// <param name="this">The data table.</param>
71-
/// <param name="rootName">Name of the XML root node.</param>
72-
/// <returns>An XML document.</returns>
73-
/// <exception cref="ArgumentNullException">dataTable or rootName</exception>
74-
[SuppressMessage("Refactoring", "GCop659:Use 'var' instead of explicit type.", Justification = "The compiler does not infer DataColumn properly here so we have to use the type instead of var.")]
75-
public static XDocument ToXml(this DataTable @this, string rootName)
76-
{
77-
_ = @this ?? throw new ArgumentNullException(nameof(@this));
78-
_ = rootName ?? throw new ArgumentNullException(nameof(rootName));
79-
Contract.Ensures(Contract.Result<XDocument>() is not null);
67+
/// <summary>
68+
/// Converts the data table to XML.
69+
/// </summary>
70+
/// <param name="this">The data table.</param>
71+
/// <param name="rootName">Name of the XML root node.</param>
72+
/// <returns>An XML document.</returns>
73+
/// <exception cref="ArgumentNullException">dataTable or rootName</exception>
74+
[SuppressMessage("Refactoring", "GCop659:Use 'var' instead of explicit type.", Justification = "The compiler does not infer DataColumn properly here so we have to use the type instead of var.")]
75+
public static XDocument ToXml(this DataTable @this, string rootName)
76+
{
77+
_ = @this ?? throw new ArgumentNullException(nameof(@this));
78+
_ = rootName ?? throw new ArgumentNullException(nameof(rootName));
79+
Contract.Ensures(Contract.Result<XDocument>() is not null);
8080

81-
var xdoc = new XDocument
82-
{
83-
Declaration = new XDeclaration("1.0", "utf-8", "")
84-
};
81+
var xdoc = new XDocument
82+
{
83+
Declaration = new XDeclaration("1.0", "utf-8", "")
84+
};
8585

86-
xdoc.Add(new XElement(rootName));
86+
xdoc.Add(new XElement(rootName));
8787

88-
foreach (DataRow row in @this.Rows)
89-
{
90-
var element = new XElement(@this.TableName);
91-
foreach (DataColumn col in @this.Columns)
92-
{
93-
element.Add(new XElement(col.ColumnName, row[col].ToString()?.Trim(' ')));
94-
}
88+
foreach (DataRow row in @this.Rows)
89+
{
90+
var element = new XElement(@this.TableName);
91+
foreach (DataColumn col in @this.Columns)
92+
{
93+
element.Add(new XElement(col.ColumnName, row[col].ToString()?.Trim(' ')));
94+
}
9595

96-
xdoc.Root?.Add(element);
97-
}
96+
xdoc.Root?.Add(element);
97+
}
9898

99-
return xdoc;
100-
}
99+
return xdoc;
100+
}
101101
}

0 commit comments

Comments
 (0)