Skip to content

Commit 98d53ea

Browse files
rojiYohDeadfall
roji
and
YohDeadfall
authored
Some XML doc fixes (#3452)
Co-authored-by: Yoh Deadfall <yoh.deadfall@hotmail.com>
1 parent 6d08dfa commit 98d53ea

23 files changed

Lines changed: 381 additions & 284 deletions

‎src/Npgsql.LegacyPostgis/CodeAnnotations.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@
1212
namespace JetBrains.Annotations
1313
{
1414
/// <summary>
15-
/// Indicates that the value of the marked element could be <c>null</c> sometimes,
16-
/// so the check for <c>null</c> is necessary before its usage.
15+
/// Indicates that the value of the marked element could be <see langword="null"/> sometimes,
16+
/// so the check for <see langword="null"/> is necessary before its usage.
1717
/// </summary>
1818
/// <example><code>
1919
/// [CanBeNull] public object Test() { return null; }
@@ -31,7 +31,7 @@ public CanBeNullAttribute() {}
3131
}
3232

3333
/// <summary>
34-
/// Indicates that the value of the marked element could never be <c>null</c>.
34+
/// Indicates that the value of the marked element could never be <see langword="null"/>.
3535
/// </summary>
3636
/// <example><code>
3737
/// [NotNull] public object Foo() {

‎src/Npgsql/NameTranslation/NpgsqlSnakeCaseNameTranslator.cs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,9 @@ public NpgsqlSnakeCaseNameTranslator()
2020
/// <summary>
2121
/// Creates a new <see cref="NpgsqlSnakeCaseNameTranslator"/>.
2222
/// </summary>
23-
/// <param name="legacyMode">Uses the legacy naming convention if <c>true</c>, otherwise it uses the new naming convention.</param>
23+
/// <param name="legacyMode">
24+
/// Uses the legacy naming convention if <see langword="true"/>, otherwise it uses the new naming convention.
25+
/// </param>
2426
public NpgsqlSnakeCaseNameTranslator(bool legacyMode)
2527
=> LegacyMode = legacyMode;
2628

‎src/Npgsql/NpgsqlBinaryExporter.cs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -247,7 +247,9 @@ ValueTask<T> Read<T>(bool async, CancellationToken cancellationToken = default)
247247
/// type, for which <typeparamref name="T"/> will be a simple string but for which
248248
/// <paramref name="type"/> must be specified as <see cref="NpgsqlDbType.Jsonb"/>.
249249
/// </param>
250-
/// <param name="cancellationToken"></param>
250+
/// <param name="cancellationToken">
251+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
252+
/// </param>
251253
/// <typeparam name="T">The .NET type of the column to be read.</typeparam>
252254
/// <returns>The value of the column</returns>
253255
public ValueTask<T> ReadAsync<T>(NpgsqlDbType type, CancellationToken cancellationToken = default)

‎src/Npgsql/NpgsqlBinaryImporter.cs‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,9 @@ async Task StartRow(bool async, CancellationToken cancellationToken = default)
166166
/// Writes a single column in the current row.
167167
/// </summary>
168168
/// <param name="value">The value to be written</param>
169-
/// <param name="cancellationToken"></param>
169+
/// <param name="cancellationToken">
170+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
171+
/// </param>
170172
/// <typeparam name="T">
171173
/// The type of the column to be written. This must correspond to the actual type or data
172174
/// corruption will occur. If in doubt, use <see cref="Write{T}(T, NpgsqlDbType)"/> to manually
@@ -220,7 +222,9 @@ public void Write<T>([AllowNull] T value, NpgsqlDbType npgsqlDbType) =>
220222
/// the JSONB type, for which <typeparamref name="T"/> will be a simple string but for which
221223
/// <paramref name="npgsqlDbType"/> must be specified as <see cref="NpgsqlDbType.Jsonb"/>.
222224
/// </param>
223-
/// <param name="cancellationToken"></param>
225+
/// <param name="cancellationToken">
226+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
227+
/// </param>
224228
/// <typeparam name="T">The .NET type of the column to be written.</typeparam>
225229
public Task WriteAsync<T>([AllowNull] T value, NpgsqlDbType npgsqlDbType, CancellationToken cancellationToken = default)
226230
{
@@ -270,7 +274,9 @@ public void Write<T>([AllowNull] T value, string dataTypeName) =>
270274
/// In some cases <typeparamref name="T"/> isn't enough to infer the data type to be written to
271275
/// the database. This parameter and be used to unambiguously specify the type.
272276
/// </param>
273-
/// <param name="cancellationToken"></param>
277+
/// <param name="cancellationToken">
278+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
279+
/// </param>
274280
/// <typeparam name="T">The .NET type of the column to be written.</typeparam>
275281
public Task WriteAsync<T>([AllowNull] T value, string dataTypeName, CancellationToken cancellationToken = default)
276282
{
@@ -393,7 +399,9 @@ async Task WriteNull(bool async, CancellationToken cancellationToken = default)
393399
/// Equivalent to calling <see cref="StartRow()"/>, followed by multiple <see cref="Write{T}(T)"/>
394400
/// on each value.
395401
/// </summary>
396-
/// <param name="cancellationToken"></param>
402+
/// <param name="cancellationToken">
403+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
404+
/// </param>
397405
/// <param name="values">An array of column values to be written as a single row</param>
398406
public Task WriteRowAsync(CancellationToken cancellationToken = default, params object[] values)
399407
{

‎src/Npgsql/NpgsqlCommand.cs‎

Lines changed: 45 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -74,31 +74,33 @@ public sealed class NpgsqlCommand : DbCommand, ICloneable
7474
#region Constructors
7575

7676
/// <summary>
77-
/// Initializes a new instance of the <see cref="NpgsqlCommand">NpgsqlCommand</see> class.
77+
/// Initializes a new instance of the <see cref="NpgsqlCommand"/> class.
7878
/// </summary>
7979
public NpgsqlCommand() : this(null, null, null) {}
8080

8181
/// <summary>
82-
/// Initializes a new instance of the <see cref="NpgsqlCommand">NpgsqlCommand</see> class with the text of the query.
82+
/// Initializes a new instance of the <see cref="NpgsqlCommand"/> class with the text of the query.
8383
/// </summary>
8484
/// <param name="cmdText">The text of the query.</param>
8585
// ReSharper disable once IntroduceOptionalParameters.Global
8686
public NpgsqlCommand(string? cmdText) : this(cmdText, null, null) {}
8787

8888
/// <summary>
89-
/// Initializes a new instance of the <see cref="NpgsqlCommand">NpgsqlCommand</see> class with the text of the query and a <see cref="NpgsqlConnection">NpgsqlConnection</see>.
89+
/// Initializes a new instance of the <see cref="NpgsqlCommand"/> class with the text of the query and a
90+
/// <see cref="NpgsqlConnection"/>.
9091
/// </summary>
9192
/// <param name="cmdText">The text of the query.</param>
92-
/// <param name="connection">A <see cref="NpgsqlConnection">NpgsqlConnection</see> that represents the connection to a PostgreSQL server.</param>
93+
/// <param name="connection">A <see cref="NpgsqlConnection"/> that represents the connection to a PostgreSQL server.</param>
9394
// ReSharper disable once IntroduceOptionalParameters.Global
9495
public NpgsqlCommand(string? cmdText, NpgsqlConnection? connection) : this(cmdText, connection, null) {}
9596

9697
/// <summary>
97-
/// Initializes a new instance of the <see cref="NpgsqlCommand">NpgsqlCommand</see> class with the text of the query, a <see cref="NpgsqlConnection">NpgsqlConnection</see>, and the <see cref="NpgsqlTransaction">NpgsqlTransaction</see>.
98+
/// Initializes a new instance of the <see cref="NpgsqlCommand"/> class with the text of the query, a
99+
/// <see cref="NpgsqlConnection"/>, and the <see cref="NpgsqlTransaction"/>.
98100
/// </summary>
99101
/// <param name="cmdText">The text of the query.</param>
100-
/// <param name="connection">A <see cref="NpgsqlConnection">NpgsqlConnection</see> that represents the connection to a PostgreSQL server.</param>
101-
/// <param name="transaction">The <see cref="NpgsqlTransaction">NpgsqlTransaction</see> in which the <see cref="NpgsqlCommand">NpgsqlCommand</see> executes.</param>
102+
/// <param name="connection">A <see cref="NpgsqlConnection"/> that represents the connection to a PostgreSQL server.</param>
103+
/// <param name="transaction">The <see cref="NpgsqlTransaction"/> in which the <see cref="NpgsqlCommand"/> executes.</param>
102104
public NpgsqlCommand(string? cmdText, NpgsqlConnection? connection, NpgsqlTransaction? transaction)
103105
{
104106
GC.SuppressFinalize(this);
@@ -153,10 +155,11 @@ public override int CommandTimeout
153155
}
154156

155157
/// <summary>
156-
/// Gets or sets a value indicating how the
157-
/// <see cref="NpgsqlCommand.CommandText">CommandText</see> property is to be interpreted.
158+
/// Gets or sets a value indicating how the <see cref="NpgsqlCommand.CommandText"/> property is to be interpreted.
158159
/// </summary>
159-
/// <value>One of the <see cref="System.Data.CommandType">CommandType</see> values. The default is <see cref="System.Data.CommandType">CommandType.Text</see>.</value>
160+
/// <value>
161+
/// One of the <see cref="System.Data.CommandType"/> values. The default is <see cref="System.Data.CommandType.Text"/>.
162+
/// </value>
160163
[DefaultValue(CommandType.Text)]
161164
[Category("Data")]
162165
public override CommandType CommandType { get; set; }
@@ -171,10 +174,9 @@ protected override DbConnection? DbConnection
171174
}
172175

173176
/// <summary>
174-
/// Gets or sets the <see cref="NpgsqlConnection">NpgsqlConnection</see>
175-
/// used by this instance of the <see cref="NpgsqlCommand">NpgsqlCommand</see>.
177+
/// Gets or sets the <see cref="NpgsqlConnection"/> used by this instance of the <see cref="NpgsqlCommand"/>.
176178
/// </summary>
177-
/// <value>The connection to a data source. The default value is a null reference.</value>
179+
/// <value>The connection to a data source. The default value is <see langword="null"/>.</value>
178180
[DefaultValue(null)]
179181
[Category("Behavior")]
180182
public new NpgsqlConnection? Connection
@@ -202,7 +204,7 @@ protected override DbConnection? DbConnection
202204
/// Gets or sets how command results are applied to the DataRow when used by the
203205
/// DbDataAdapter.Update(DataSet) method.
204206
/// </summary>
205-
/// <value>One of the <see cref="System.Data.UpdateRowSource">UpdateRowSource</see> values.</value>
207+
/// <value>One of the <see cref="System.Data.UpdateRowSource"/> values.</value>
206208
[Category("Behavior"), DefaultValue(UpdateRowSource.Both)]
207209
public override UpdateRowSource UpdatedRowSource
208210
{
@@ -318,30 +320,24 @@ internal CommandState State
318320
#region Parameters
319321

320322
/// <summary>
321-
/// Creates a new instance of an <see cref="System.Data.Common.DbParameter">DbParameter</see> object.
323+
/// Creates a new instance of an <see cref="System.Data.Common.DbParameter"/> object.
322324
/// </summary>
323-
/// <returns>An <see cref="System.Data.Common.DbParameter">DbParameter</see> object.</returns>
324-
protected override DbParameter CreateDbParameter()
325-
{
326-
return CreateParameter();
327-
}
325+
/// <returns>A <see cref="System.Data.Common.DbParameter"/> object.</returns>
326+
protected override DbParameter CreateDbParameter() => CreateParameter();
328327

329328
/// <summary>
330-
/// Creates a new instance of a <see cref="NpgsqlParameter">NpgsqlParameter</see> object.
329+
/// Creates a new instance of a <see cref="NpgsqlParameter"/> object.
331330
/// </summary>
332-
/// <returns>A <see cref="NpgsqlParameter">NpgsqlParameter</see> object.</returns>
333-
public new NpgsqlParameter CreateParameter()
334-
{
335-
return new();
336-
}
331+
/// <returns>An <see cref="NpgsqlParameter"/> object.</returns>
332+
public new NpgsqlParameter CreateParameter() => new();
337333

338334
/// <summary>
339335
/// DB parameter collection.
340336
/// </summary>
341337
protected override DbParameterCollection DbParameterCollection => Parameters;
342338

343339
/// <summary>
344-
/// Gets the <see cref="NpgsqlParameterCollection">NpgsqlParameterCollection</see>.
340+
/// Gets the <see cref="NpgsqlParameterCollection"/>.
345341
/// </summary>
346342
/// <value>The parameters of the SQL statement or function (stored procedure). The default is an empty collection.</value>
347343
public new NpgsqlParameterCollection Parameters => _parameters;
@@ -547,7 +543,9 @@ void DeriveParametersForQuery(NpgsqlConnector connector)
547543
/// Creates a server-side prepared statement on the PostgreSQL server.
548544
/// This will make repeated future executions of this command much faster.
549545
/// </summary>
550-
/// <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None"/>.</param>
546+
/// <param name="cancellationToken">
547+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
548+
/// </param>
551549
#if NETSTANDARD2_0
552550
public Task PrepareAsync(CancellationToken cancellationToken = default)
553551
#else
@@ -682,7 +680,9 @@ public void Unprepare()
682680
/// Note that this only affects commands explicitly prepared with <see cref="Prepare()"/>, not
683681
/// automatically prepared statements.
684682
/// </summary>
685-
/// <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None"/>.</param>
683+
/// <param name="cancellationToken">
684+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
685+
/// </param>
686686
public Task UnprepareAsync(CancellationToken cancellationToken = default)
687687
{
688688
using (NoSynchronizationContextScope.Enter())
@@ -1021,7 +1021,9 @@ async Task SendClose(NpgsqlConnector connector, bool async, CancellationToken ca
10211021
/// <summary>
10221022
/// Asynchronous version of <see cref="ExecuteNonQuery()"/>
10231023
/// </summary>
1024-
/// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
1024+
/// <param name="cancellationToken">
1025+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
1026+
/// </param>
10251027
/// <returns>A task representing the asynchronous operation, with the number of rows affected if known; -1 otherwise.</returns>
10261028
public override Task<int> ExecuteNonQueryAsync(CancellationToken cancellationToken)
10271029
{
@@ -1053,7 +1055,9 @@ async Task<int> ExecuteNonQuery(bool async, CancellationToken cancellationToken)
10531055
/// <summary>
10541056
/// Asynchronous version of <see cref="ExecuteScalar()"/>
10551057
/// </summary>
1056-
/// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
1058+
/// <param name="cancellationToken">
1059+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
1060+
/// </param>
10571061
/// <returns>A task representing the asynchronous operation, with the first column of the
10581062
/// first row in the result set, or a null reference if the result set is empty.</returns>
10591063
public override Task<object?> ExecuteScalarAsync(CancellationToken cancellationToken)
@@ -1088,7 +1092,9 @@ protected override DbDataReader ExecuteDbDataReader(CommandBehavior behavior)
10881092
/// Executes the command text against the connection.
10891093
/// </summary>
10901094
/// <param name="behavior">An instance of <see cref="CommandBehavior"/>.</param>
1091-
/// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
1095+
/// <param name="cancellationToken">
1096+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
1097+
/// </param>
10921098
/// <returns>A task representing the asynchronous operation.</returns>
10931099
protected override async Task<DbDataReader> ExecuteDbDataReaderAsync(CommandBehavior behavior, CancellationToken cancellationToken)
10941100
=> await ExecuteReaderAsync(behavior, cancellationToken);
@@ -1107,7 +1113,9 @@ protected override async Task<DbDataReader> ExecuteDbDataReaderAsync(CommandBeha
11071113
/// the <see cref="CommandText"/> against the <see cref="Connection"/>
11081114
/// and returns a <see cref="NpgsqlDataReader"/>.
11091115
/// </summary>
1110-
/// <param name="cancellationToken">The token to monitor for cancellation requests. The default value is <see cref="CancellationToken.None"/>.</param>
1116+
/// <param name="cancellationToken">
1117+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
1118+
/// </param>
11111119
/// <returns>A task representing the asynchronous operation.</returns>
11121120
public new Task<NpgsqlDataReader> ExecuteReaderAsync(CancellationToken cancellationToken = default)
11131121
=> ExecuteReaderAsync(CommandBehavior.Default, cancellationToken);
@@ -1118,7 +1126,9 @@ protected override async Task<DbDataReader> ExecuteDbDataReaderAsync(CommandBeha
11181126
/// and returns a <see cref="NpgsqlDataReader"/>.
11191127
/// </summary>
11201128
/// <param name="behavior">One of the enumeration values that specified the command behavior.</param>
1121-
/// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
1129+
/// <param name="cancellationToken">
1130+
/// An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.
1131+
/// </param>
11221132
/// <returns>A task representing the asynchronous operation.</returns>
11231133
public new Task<NpgsqlDataReader> ExecuteReaderAsync(CommandBehavior behavior, CancellationToken cancellationToken = default)
11241134
{
@@ -1354,7 +1364,7 @@ public override void Cancel()
13541364
#region Dispose
13551365

13561366
/// <summary>
1357-
/// Releases the resources used by the <see cref="NpgsqlCommand">NpgsqlCommand</see>.
1367+
/// Releases the resources used by the <see cref="NpgsqlCommand"/>.
13581368
/// </summary>
13591369
protected override void Dispose(bool disposing)
13601370
{

0 commit comments

Comments
 (0)