Skip to content

Commit 9848510

Browse files
JoshCloseJoshClose
committed
Merge branch 'MarcelVersteeg-documentation'
2 parents 7634db3 + 8d1ebbb commit 9848510

3 files changed

Lines changed: 124 additions & 30 deletions

File tree

‎src/CsvHelper/CsvParser.cs‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2009-2022 Josh Close
1+
// Copyright 2009-2022 Josh Close
22
// This file is a part of CsvHelper and is dual licensed under MS-PL and Apache 2.0.
33
// See LICENSE.txt for details or visit http://www.opensource.org/licenses/ms-pl.html for MS-PL and http://opensource.org/licenses/Apache-2.0 for Apache 2.0.
44
// https://github.com/JoshClose/CsvHelper
@@ -836,7 +836,13 @@ private string GetField(int index)
836836
return value;
837837
}
838838

839-
/// <inheritdoc/>
839+
/// <summary>
840+
/// Processes a field that complies with RFC4180.
841+
/// </summary>
842+
/// <param name="start">The start index of the field.</param>
843+
/// <param name="length">The length of the field.</param>
844+
/// <param name="quoteCount">The number of counted quotes.</param>
845+
/// <returns>The processed field.</returns>
840846
protected ProcessedField ProcessRFC4180Field(int start, int length, int quoteCount)
841847
{
842848
var newStart = start;
@@ -924,7 +930,12 @@ protected ProcessedField ProcessRFC4180Field(int start, int length, int quoteCou
924930
return new ProcessedField(0, position, processFieldBuffer);
925931
}
926932

927-
/// <inheritdoc/>
933+
/// <summary>
934+
/// Processes a field that does not comply with RFC4180.
935+
/// </summary>
936+
/// <param name="start">The start index of the field.</param>
937+
/// <param name="length">The length of the field.</param>
938+
/// <returns>The processed field.</returns>
928939
protected ProcessedField ProcessRFC4180BadField(int start, int length)
929940
{
930941
// If field is already known to be bad, different rules can be applied.
@@ -1003,7 +1014,12 @@ protected ProcessedField ProcessRFC4180BadField(int start, int length)
10031014
return new ProcessedField(0, position, processFieldBuffer);
10041015
}
10051016

1006-
/// <inheritdoc/>
1017+
/// <summary>
1018+
/// Processes an escaped field.
1019+
/// </summary>
1020+
/// <param name="start">The start index of the field.</param>
1021+
/// <param name="length">The length of the field.</param>
1022+
/// <returns>The processed field.</returns>
10071023
protected ProcessedField ProcessEscapeField(int start, int length)
10081024
{
10091025
var newStart = start;
@@ -1050,6 +1066,12 @@ protected ProcessedField ProcessEscapeField(int start, int length)
10501066
}
10511067

10521068
/// <inheritdoc/>
1069+
/// <summary>
1070+
/// Processes an non-escaped field.
1071+
/// </summary>
1072+
/// <param name="start">The start index of the field.</param>
1073+
/// <param name="length">The length of the field.</param>
1074+
/// <returns>The processed field.</returns>
10531075
protected ProcessedField ProcessNoEscapeField(int start, int length)
10541076
{
10551077
var newStart = start;
@@ -1071,7 +1093,10 @@ public void Dispose()
10711093
GC.SuppressFinalize(this);
10721094
}
10731095

1074-
/// <inheritdoc/>
1096+
/// <summary>
1097+
/// Disposes the object.
1098+
/// </summary>
1099+
/// <param name="disposing">Indicates if the object is being disposed.</param>
10751100
protected virtual void Dispose(bool disposing)
10761101
{
10771102
if (disposed)

‎src/CsvHelper/CsvReader.cs‎

Lines changed: 57 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2009-2022 Josh Close
1+
// Copyright 2009-2022 Josh Close
22
// This file is a part of CsvHelper and is dual licensed under MS-PL and Apache 2.0.
33
// See LICENSE.txt for details or visit http://www.opensource.org/licenses/ms-pl.html for MS-PL and http://opensource.org/licenses/Apache-2.0 for Apache 2.0.
44
// https://github.com/JoshClose/CsvHelper
@@ -14,6 +14,7 @@
1414
using System.Globalization;
1515
using System.Runtime.CompilerServices;
1616
using System.Threading;
17+
using System.Configuration;
1718

1819
namespace CsvHelper
1920
{
@@ -120,13 +121,19 @@ public virtual bool ReadHeader()
120121
return headerRecord != null;
121122
}
122123

123-
/// <inheritdoc/>
124+
/// <summary>
125+
/// Validates the header to be of the given type.
126+
/// </summary>
127+
/// <typeparam name="T">The expected type of the header</typeparam>
124128
public virtual void ValidateHeader<T>()
125129
{
126130
ValidateHeader(typeof(T));
127131
}
128132

129-
/// <inheritdoc/>
133+
/// <summary>
134+
/// Validates the header to be of the given type.
135+
/// </summary>
136+
/// <param name="type">The expected type of the header.</param>
130137
public virtual void ValidateHeader(Type type)
131138
{
132139
if (hasHeaderRecord == false)
@@ -154,7 +161,11 @@ public virtual void ValidateHeader(Type type)
154161
headerValidated?.Invoke(args);
155162
}
156163

157-
/// <inheritdoc/>
164+
/// <summary>
165+
/// Validates the header to be of the given type.
166+
/// </summary>
167+
/// <param name="map">The mapped classes.</param>
168+
/// <param name="invalidHeaders">The invalid headers.</param>
158169
protected virtual void ValidateHeader(ClassMap map, List<InvalidHeader> invalidHeaders)
159170
{
160171
foreach (var parameter in map.ParameterMaps)
@@ -344,8 +355,8 @@ public virtual string? this[string name]
344355

345356
if (index >= parser.Count || index < 0)
346357
{
347-
var args = new MissingFieldFoundArgs(null, index, context);
348-
missingFieldFound?.Invoke(args);
358+
var args = new MissingFieldFoundArgs(null, index, context);
359+
missingFieldFound?.Invoke(args);
349360
return default;
350361
}
351362

@@ -481,8 +492,8 @@ public virtual string? this[string name]
481492
if (index >= parser.Count || index < 0)
482493
{
483494
currentIndex = index;
484-
var args = new MissingFieldFoundArgs(null, index, context);
485-
missingFieldFound?.Invoke(args);
495+
var args = new MissingFieldFoundArgs(null, index, context);
496+
missingFieldFound?.Invoke(args);
486497

487498
return default;
488499
}
@@ -1011,7 +1022,7 @@ public virtual IEnumerable<T> EnumerateRecords<T>(T record)
10111022

10121023
#if !NET45
10131024
/// <inheritdoc/>
1014-
public virtual async IAsyncEnumerable<T> GetRecordsAsync<T>([EnumeratorCancellation]CancellationToken cancellationToken = default(CancellationToken))
1025+
public virtual async IAsyncEnumerable<T> GetRecordsAsync<T>([EnumeratorCancellation] CancellationToken cancellationToken = default(CancellationToken))
10151026
{
10161027
if (disposed)
10171028
{
@@ -1203,13 +1214,26 @@ public virtual async IAsyncEnumerable<T> EnumerateRecordsAsync<T>(T record, [Enu
12031214
}
12041215
#endif
12051216

1206-
/// <inheritdoc/>
1217+
/// <summary>
1218+
/// Gets the index of the field with the given name.
1219+
/// </summary>
1220+
/// <param name="name">The name of the field.</param>
1221+
/// <param name="index">The index of the field.</param>
1222+
/// <param name="isTryGet">Indicates if a TryGet is executed.</param>
1223+
/// <returns>The index of the field.</returns>
12071224
public virtual int GetFieldIndex(string name, int index = 0, bool isTryGet = false)
12081225
{
12091226
return GetFieldIndex(new[] { name }, index, isTryGet);
12101227
}
12111228

1212-
/// <inheritdoc/>
1229+
/// <summary>
1230+
/// Gets the index of the field with the given name.
1231+
/// </summary>
1232+
/// <param name="names">The names of the field.</param>
1233+
/// <param name="index">The index of the field.</param>
1234+
/// <param name="isTryGet">Indicates if a TryGet is executed.</param>
1235+
/// <param name="isOptional">Indicates if the field is optional.</param>
1236+
/// <returns>The index of the field.</returns>
12131237
public virtual int GetFieldIndex(IEnumerable<string> names, int index = 0, bool isTryGet = false, bool isOptional = false)
12141238
{
12151239
if (names == null)
@@ -1270,7 +1294,11 @@ public virtual int GetFieldIndex(IEnumerable<string> names, int index = 0, bool
12701294
return namedIndexes[name][index];
12711295
}
12721296

1273-
/// <inheritdoc/>
1297+
/// <summary>
1298+
/// Indicates if values can be read.
1299+
/// </summary>
1300+
/// <param name="memberMap">The member map.</param>
1301+
/// <returns>True if values can be read.</returns>
12741302
public virtual bool CanRead(MemberMap memberMap)
12751303
{
12761304
var cantRead =
@@ -1291,7 +1319,11 @@ public virtual bool CanRead(MemberMap memberMap)
12911319
return !cantRead;
12921320
}
12931321

1294-
/// <inheritdoc/>
1322+
/// <summary>
1323+
/// Indicates if values can be read.
1324+
/// </summary>
1325+
/// <param name="memberReferenceMap">The member reference map.</param>
1326+
/// <returns>True if values can be read.</returns>
12951327
public virtual bool CanRead(MemberReferenceMap memberReferenceMap)
12961328
{
12971329
var cantRead = false;
@@ -1317,7 +1349,10 @@ public void Dispose()
13171349
GC.SuppressFinalize(this);
13181350
}
13191351

1320-
/// <inheritdoc/>
1352+
/// <summary>
1353+
/// Disposes the object.
1354+
/// </summary>
1355+
/// <param name="disposing">Indicates if the object is being disposed.</param>
13211356
protected virtual void Dispose(bool disposing)
13221357
{
13231358
if (disposed)
@@ -1338,7 +1373,10 @@ protected virtual void Dispose(bool disposing)
13381373
disposed = true;
13391374
}
13401375

1341-
/// <inheritdoc/>
1376+
/// <summary>
1377+
/// Checks if the file has been read.
1378+
/// </summary>
1379+
/// <exception cref="ReaderException">Thrown when the file has not yet been read.</exception>
13421380
[MethodImpl(MethodImplOptions.AggressiveInlining)]
13431381
protected virtual void CheckHasBeenRead()
13441382
{
@@ -1348,7 +1386,10 @@ protected virtual void CheckHasBeenRead()
13481386
}
13491387
}
13501388

1351-
/// <inheritdoc/>
1389+
/// <summary>
1390+
/// Parses the named indexes.
1391+
/// </summary>
1392+
/// <exception cref="ReaderException">Thrown when no header record was found.</exception>
13521393
[MethodImpl(MethodImplOptions.AggressiveInlining)]
13531394
protected virtual void ParseNamedIndexes()
13541395
{

‎src/CsvHelper/CsvWriter.cs‎

Lines changed: 37 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2009-2022 Josh Close
1+
// Copyright 2009-2022 Josh Close
22
// This file is a part of CsvHelper and is dual licensed under MS-PL and Apache 2.0.
33
// See LICENSE.txt for details or visit http://www.opensource.org/licenses/ms-pl.html for MS-PL and http://opensource.org/licenses/Apache-2.0 for Apache 2.0.
44
// https://github.com/JoshClose/CsvHelper
@@ -299,7 +299,11 @@ public virtual void WriteHeader(Type type)
299299
hasHeaderBeenWritten = true;
300300
}
301301

302-
/// <inheritdoc/>
302+
/// <summary>
303+
/// Writes a dynamic header record.
304+
/// </summary>
305+
/// <param name="record">The header record to write.</param>
306+
/// <exception cref="ArgumentNullException">Thrown when no record is passed.</exception>
303307
public virtual void WriteDynamicHeader(IDynamicMetaObjectProvider record)
304308
{
305309
if (record == null)
@@ -526,23 +530,31 @@ public virtual async Task FlushAsync()
526530
await writer.FlushAsync().ConfigureAwait(false);
527531
}
528532

529-
/// <inheritdoc/>
533+
/// <summary>
534+
/// Flushes the buffer.
535+
/// </summary>
530536
[MethodImpl(MethodImplOptions.AggressiveInlining)]
531537
protected virtual void FlushBuffer()
532538
{
533539
writer.Write(buffer, 0, bufferPosition);
534540
bufferPosition = 0;
535541
}
536542

537-
/// <inheritdoc/>
543+
/// <summary>
544+
/// Asynchronously flushes the buffer.
545+
/// </summary>
538546
[MethodImpl(MethodImplOptions.AggressiveInlining)]
539547
protected virtual async Task FlushBufferAsync()
540548
{
541549
await writer.WriteAsync(buffer, 0, bufferPosition).ConfigureAwait(false);
542550
bufferPosition = 0;
543551
}
544552

545-
/// <inheritdoc/>
553+
/// <summary>
554+
/// Indicates if values can be written.
555+
/// </summary>
556+
/// <param name="memberMap">The member map.</param>
557+
/// <returns>True if values can be written.</returns>
546558
public virtual bool CanWrite(MemberMap memberMap)
547559
{
548560
var cantWrite =
@@ -562,7 +574,12 @@ public virtual bool CanWrite(MemberMap memberMap)
562574
return !cantWrite;
563575
}
564576

565-
/// <inheritdoc/>
577+
/// <summary>
578+
/// Determines the type for the given record.
579+
/// </summary>
580+
/// <typeparam name="T">The type of the record.</typeparam>
581+
/// <param name="record">The record to determine the type of.</param>
582+
/// <returns>The System.Type for the record.</returns>
566583
public virtual Type GetTypeForRecord<T>(T record)
567584
{
568585
var type = typeof(T);
@@ -574,7 +591,12 @@ public virtual Type GetTypeForRecord<T>(T record)
574591
return type;
575592
}
576593

577-
/// <inheritdoc/>
594+
/// <summary>
595+
/// Sanitizes the given field, before it is injected.
596+
/// </summary>
597+
/// <param name="field">The field to sanitize.</param>
598+
/// <returns>The sanitized field.</returns>
599+
/// <exception cref="WriterException">Thrown when an injection character is found in the field.</exception>
578600
[MethodImpl(MethodImplOptions.AggressiveInlining)]
579601
protected virtual string SanitizeForInjection(string field)
580602
{
@@ -636,7 +658,10 @@ protected virtual string SanitizeForInjection(string field)
636658
return field;
637659
}
638660

639-
/// <inheritdoc/>
661+
/// <summary>
662+
/// Writes the given value to the buffer.
663+
/// </summary>
664+
/// <param name="value">The value to write.</param>
640665
[MethodImpl(MethodImplOptions.AggressiveInlining)]
641666
protected void WriteToBuffer(string value)
642667
{
@@ -670,7 +695,10 @@ public void Dispose()
670695
GC.SuppressFinalize(this);
671696
}
672697

673-
/// <inheritdoc/>
698+
/// <summary>
699+
/// Disposes the object.
700+
/// </summary>
701+
/// <param name="disposing">Indicates if the object is being disposed.</param>
674702
protected virtual void Dispose(bool disposing)
675703
{
676704
if (disposed)

0 commit comments

Comments
 (0)