Skip to content

Commit a67c838

Browse files
author
Fahad Adeel
committed
Enhance API Documentation and Add Exception Handling
- Updated XML comments across various classes (Worksheet, Range, etc.) for improved API documentation. - Added detailed descriptions, parameter info, and return types to the comments for better clarity in generated docs. - Incorporated exception handling in methods where necessary, including validation checks for input arguments. - Ensured consistency in commenting style to align with best practices in C# XML documentation.
1 parent 91fe429 commit a67c838

File tree

2 files changed

+688
-425
lines changed

2 files changed

+688
-425
lines changed

FileFormat.Cells/Range.cs

+79-6
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,64 @@ public class Range
1515
public uint EndRowIndex { get; }
1616
public uint EndColumnIndex { get; }
1717

18-
// Returns the count of columns in the range
18+
/// <summary>
19+
/// Gets the count of columns in the range.
20+
/// This property calculates the column count based on the start and end column indices.
21+
/// </summary>
22+
/// <value>
23+
/// The count of columns in the range.
24+
/// </value>
25+
/// <exception cref="InvalidOperationException">
26+
/// Thrown if the end column index is less than the start column index.
27+
/// </exception>
1928
public uint ColumnCount
2029
{
21-
get { return EndColumnIndex - StartColumnIndex + 1; }
30+
get
31+
{
32+
if (EndColumnIndex < StartColumnIndex)
33+
{
34+
throw new InvalidOperationException("End column index cannot be less than start column index.");
35+
}
36+
return EndColumnIndex - StartColumnIndex + 1;
37+
}
2238
}
2339

24-
// Returns the count of rows in the range
40+
/// <summary>
41+
/// Gets the count of rows in the range.
42+
/// This property calculates the row count based on the start and end row indices.
43+
/// </summary>
44+
/// <value>
45+
/// The count of rows in the range.
46+
/// </value>
47+
/// <exception cref="InvalidOperationException">
48+
/// Thrown if the end row index is less than the start row index.
49+
/// </exception>
2550
public uint RowCount
2651
{
27-
get { return EndRowIndex - StartRowIndex + 1; }
52+
get
53+
{
54+
if (EndRowIndex < StartRowIndex)
55+
{
56+
throw new InvalidOperationException("End row index cannot be less than start row index.");
57+
}
58+
return EndRowIndex - StartRowIndex + 1;
59+
}
2860
}
2961

30-
62+
/// <summary>
63+
/// Initializes a new instance of the Range class.
64+
/// </summary>
65+
/// <param name="worksheet">The worksheet to which this range belongs.</param>
66+
/// <param name="startRowIndex">The starting row index of the range.</param>
67+
/// <param name="startColumnIndex">The starting column index of the range.</param>
68+
/// <param name="endRowIndex">The ending row index of the range.</param>
69+
/// <param name="endColumnIndex">The ending column index of the range.</param>
70+
/// <exception cref="ArgumentNullException">
71+
/// Thrown if the provided worksheet is null.
72+
/// </exception>
73+
/// <exception cref="ArgumentOutOfRangeException">
74+
/// Thrown if the start or end row/column indices are out of range.
75+
/// </exception>
3176
public Range(Worksheet worksheet, uint startRowIndex, uint startColumnIndex, uint endRowIndex, uint endColumnIndex)
3277
{
3378
_worksheet = worksheet ?? throw new ArgumentNullException(nameof(worksheet));
@@ -37,6 +82,13 @@ public Range(Worksheet worksheet, uint startRowIndex, uint startColumnIndex, uin
3782
EndColumnIndex = endColumnIndex;
3883
}
3984

85+
/// <summary>
86+
/// Sets the specified value to all cells within the range.
87+
/// </summary>
88+
/// <param name="value">The value to set in each cell of the range.</param>
89+
/// <exception cref="InvalidOperationException">
90+
/// Thrown if any cell within the range is not properly initialized or accessible.
91+
/// </exception>
4092
public void SetValue(string value)
4193
{
4294
for (uint row = StartRowIndex; row <= EndRowIndex; row++)
@@ -50,6 +102,12 @@ public void SetValue(string value)
50102
}
51103
}
52104

105+
/// <summary>
106+
/// Clears the values and resets the style of all cells within the range.
107+
/// </summary>
108+
/// <exception cref="InvalidOperationException">
109+
/// Thrown if any cell within the range is not properly initialized or accessible.
110+
/// </exception>
53111
public void ClearCells()
54112
{
55113
for (uint row = StartRowIndex; row <= EndRowIndex; row++)
@@ -67,6 +125,12 @@ public void ClearCells()
67125
}
68126
}
69127

128+
/// <summary>
129+
/// Merges all cells within the range into a single cell.
130+
/// </summary>
131+
/// <exception cref="InvalidOperationException">
132+
/// Thrown if the merge operation fails, for example, if the cells cannot be merged.
133+
/// </exception>
70134
public void MergeCells()
71135
{
72136
string startCellReference = $"{ColumnIndexToLetter(StartColumnIndex)}{StartRowIndex}";
@@ -75,7 +139,16 @@ public void MergeCells()
75139
_worksheet.MergeCells(startCellReference, endCellReference);
76140
}
77141

78-
142+
/// <summary>
143+
/// Adds dropdown list validation with the specified options to all cells within the range.
144+
/// </summary>
145+
/// <param name="options">The list of options for the dropdown validation.</param>
146+
/// <exception cref="ArgumentNullException">
147+
/// Thrown if the options array is null or empty.
148+
/// </exception>
149+
/// <exception cref="InvalidOperationException">
150+
/// Thrown if adding dropdown validation fails for any cell within the range.
151+
/// </exception>
79152
public void AddDropdownListValidation(string[] options)
80153
{
81154

0 commit comments

Comments
 (0)