Skip to content

Commit 0e63d12

Browse files
bartonjsmairaw
authored and
carlossanlop
committed
Add missing, and update existing, documentation on the HashAlgorithm classes. (dotnet#3617)
* Add missing, and update existing, documentation on the HashAlgorithm classes * Apply suggestions from code review Co-Authored-By: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> * Apply suggestions from code review Co-Authored-By: Maira Wenzel <mairaw@microsoft.com>
1 parent 88f6ae4 commit 0e63d12

File tree

12 files changed

+214
-155
lines changed

12 files changed

+214
-155
lines changed

‎xml/System.Security.Cryptography/HMAC.xml‎

Lines changed: 36 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -346,9 +346,20 @@
346346
<Parameter Name="source" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
347347
</Parameters>
348348
<Docs>
349-
<param name="source">To be added.</param>
350-
<summary>To be added.</summary>
351-
<remarks>To be added.</remarks>
349+
<param name="source">The input to compute the HMAC code for.</param>
350+
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
351+
<remarks>
352+
<format type="text/markdown"><![CDATA[
353+
354+
## Remarks
355+
The default implementation of this method throws a <xref:System.PlatformNotSupportedException>
356+
because there is no managed implementation of HMAC.
357+
358+
Derived types must override this method.
359+
360+
]]></format>
361+
</remarks>
362+
<exception cref="T:System.PlatformNotSupportedException">In all cases.</exception>
352363
</Docs>
353364
</Member>
354365
<Member MemberName="HashCore">
@@ -388,15 +399,13 @@
388399
<param name="rgb">The input data.</param>
389400
<param name="ib">The offset into the byte array from which to begin using data.</param>
390401
<param name="cb">The number of bytes in the array to use as data.</param>
391-
<summary>When overridden in a derived class, routes data written to the object into the default <see cref="T:System.Security.Cryptography.HMAC" /> hash algorithm for computing the hash value.</summary>
402+
<summary>When overridden in a derived class, routes data written to the object into the HMAC algorithm for computing the HMAC value.</summary>
392403
<remarks>
393404
<format type="text/markdown"><![CDATA[
394405
395406
## Remarks
396407
This method is not called by application code.
397408
398-
This abstract method performs the hash computation. Every write to the cryptographic stream object passes the data through this method. For each block of data, this method updates the state of the hash object so that a correct hash value is returned at the end of the data stream.
399-
400409
]]></format>
401410
</remarks>
402411
<altmember cref="T:System.Security.Cryptography.HashAlgorithm" />
@@ -433,8 +442,8 @@
433442
</ReturnValue>
434443
<Parameters />
435444
<Docs>
436-
<summary>When overridden in a derived class, finalizes the hash computation after the last data is processed by the cryptographic stream object.</summary>
437-
<returns>The computed hash code in a byte array.</returns>
445+
<summary>When overridden in a derived class, finalizes the HMAC computation after the last data is processed by the algorithm.</summary>
446+
<returns>The computed HMAC value in a byte array.</returns>
438447
<remarks>
439448
<format type="text/markdown"><![CDATA[
440449
@@ -562,8 +571,8 @@
562571
<ReturnType>System.Byte[]</ReturnType>
563572
</ReturnValue>
564573
<Docs>
565-
<summary>Gets or sets the key to use in the hash algorithm.</summary>
566-
<value>The key to use in the hash algorithm.</value>
574+
<summary>Gets or sets the key to use in the HMAC calculation.</summary>
575+
<value>The key to use in the HMAC calculation.</value>
567576
<remarks>
568577
<format type="text/markdown"><![CDATA[
569578
@@ -611,11 +620,23 @@
611620
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
612621
</Parameters>
613622
<Docs>
614-
<param name="destination">To be added.</param>
615-
<param name="bytesWritten">To be added.</param>
616-
<summary>To be added.</summary>
617-
<returns>To be added.</returns>
618-
<remarks>To be added.</remarks>
623+
<param name="destination">The buffer to receive the HMAC value.</param>
624+
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
625+
<summary>Attempts to finalize the HMAC computation after the last data is processed by the HMAC algorithm.</summary>
626+
<returns>
627+
<see langword="true"/> if <paramref name="destination"/> is long enough to receive the HMAC value; otherwise, <see langword="false"/>.</returns>
628+
<remarks>
629+
<format type="text/markdown"><![CDATA[
630+
631+
## Remarks
632+
The default implementation of this method throws a <xref:System.PlatformNotSupportedException>
633+
because there is no managed implementation of HMAC.
634+
635+
Derived types must override this method.
636+
637+
]]></format>
638+
</remarks>
639+
<exception cref="T:System.PlatformNotSupportedException">The method is not overriden in the derived type.</exception>
619640
</Docs>
620641
</Member>
621642
</Members>

‎xml/System.Security.Cryptography/HMACMD5.xml‎

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -199,8 +199,9 @@
199199
<Parameter Name="disposing" Type="System.Boolean" Index="0" FrameworkAlternate="netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.1" />
200200
</Parameters>
201201
<Docs>
202-
<param name="disposing">To be added.</param>
203-
<summary>To be added.</summary>
202+
<param name="disposing">
203+
<see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.</param>
204+
<summary>Releases the unmanaged resources used by the <see cref="T:System.Security.Cryptography.HMACMD5" /> and optionally releases the managed resources.</summary>
204205
<remarks>To be added.</remarks>
205206
</Docs>
206207
</Member>
@@ -230,8 +231,8 @@
230231
<Parameter Name="source" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
231232
</Parameters>
232233
<Docs>
233-
<param name="source">To be added.</param>
234-
<summary>To be added.</summary>
234+
<param name="source">The input to compute the HMAC for.</param>
235+
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
235236
<remarks>To be added.</remarks>
236237
</Docs>
237238
</Member>
@@ -267,10 +268,10 @@
267268
<Parameter Name="cb" Type="System.Int32" Index="2" FrameworkAlternate="netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.1" />
268269
</Parameters>
269270
<Docs>
270-
<param name="rgb">To be added.</param>
271-
<param name="ib">To be added.</param>
272-
<param name="cb">To be added.</param>
273-
<summary>To be added.</summary>
271+
<param name="rgb">The input to compute the HMAC for.</param>
272+
<param name="ib">The offset into the byte array from which to begin using data.</param>
273+
<param name="cb">The number of bytes in the byte array to use as data.</param>
274+
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
274275
<remarks>To be added.</remarks>
275276
</Docs>
276277
</Member>
@@ -302,8 +303,8 @@
302303
</ReturnValue>
303304
<Parameters />
304305
<Docs>
305-
<summary>To be added.</summary>
306-
<returns>To be added.</returns>
306+
<summary>Finalizes the HMAC computation after the last data is processed by the algorithm.</summary>
307+
<returns>The computed HMAC value in a byte array.</returns>
307308
<remarks>To be added.</remarks>
308309
</Docs>
309310
</Member>
@@ -331,8 +332,8 @@
331332
<ReturnType>System.Int32</ReturnType>
332333
</ReturnValue>
333334
<Docs>
334-
<summary>To be added.</summary>
335-
<value>To be added.</value>
335+
<summary>Gets the size, in bits, of the computed HMAC.</summary>
336+
<value>The size, in bits, of the computed HMAC.</value>
336337
<remarks>To be added.</remarks>
337338
</Docs>
338339
</Member>
@@ -364,7 +365,7 @@
364365
</ReturnValue>
365366
<Parameters />
366367
<Docs>
367-
<summary>To be added.</summary>
368+
<summary>Resets the hash algorithm to its initial state.</summary>
368369
<remarks>To be added.</remarks>
369370
</Docs>
370371
</Member>
@@ -395,8 +396,8 @@
395396
<ReturnType>System.Byte[]</ReturnType>
396397
</ReturnValue>
397398
<Docs>
398-
<summary>To be added.</summary>
399-
<value>To be added.</value>
399+
<summary>Gets or sets the key to use in the HMAC calculation.</summary>
400+
<value>The key to use in the HMAC calculation.</value>
400401
<remarks>To be added.</remarks>
401402
</Docs>
402403
</Member>
@@ -427,10 +428,11 @@
427428
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
428429
</Parameters>
429430
<Docs>
430-
<param name="destination">To be added.</param>
431-
<param name="bytesWritten">To be added.</param>
432-
<summary>To be added.</summary>
433-
<returns>To be added.</returns>
431+
<param name="destination">The buffer to receive the HMAC value.</param>
432+
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
433+
<summary>Attempts to finalize the HMAC computation after the last data is processed by the HMAC algorithm.</summary>
434+
<returns>
435+
<see langword="true"/> if <paramref name="destination"/> is long enough to receive the HMAC value; otherwise, <see langword="false"/>.</returns>
434436
<remarks>To be added.</remarks>
435437
</Docs>
436438
</Member>

‎xml/System.Security.Cryptography/HMACSHA1.xml‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -316,8 +316,8 @@ Releases the unmanaged resources used by the <see cref="T:System.Security.Crypto
316316
<Parameter Name="source" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
317317
</Parameters>
318318
<Docs>
319-
<param name="source">To be added.</param>
320-
<summary>To be added.</summary>
319+
<param name="source">The input to compute the HMAC for.</param>
320+
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
321321
<remarks>To be added.</remarks>
322322
</Docs>
323323
</Member>
@@ -390,8 +390,8 @@ Releases the unmanaged resources used by the <see cref="T:System.Security.Crypto
390390
</ReturnValue>
391391
<Parameters />
392392
<Docs>
393-
<summary>To be added.</summary>
394-
<returns>To be added.</returns>
393+
<summary>Finalizes the HMAC computation after the last data is processed by the algorithm.</summary>
394+
<returns>The computed HMAC value in a byte array.</returns>
395395
<remarks>To be added.</remarks>
396396
</Docs>
397397
</Member>
@@ -446,8 +446,8 @@ Releases the unmanaged resources used by the <see cref="T:System.Security.Crypto
446446
<ReturnType>System.Int32</ReturnType>
447447
</ReturnValue>
448448
<Docs>
449-
<summary>To be added.</summary>
450-
<value>To be added.</value>
449+
<summary>Gets the size, in bits, of the computed HMAC.</summary>
450+
<value>The size, in bits, of the computed HMAC.</value>
451451
<remarks>To be added.</remarks>
452452
</Docs>
453453
</Member>
@@ -480,7 +480,7 @@ Releases the unmanaged resources used by the <see cref="T:System.Security.Crypto
480480
</ReturnValue>
481481
<Parameters />
482482
<Docs>
483-
<summary>Initializes an instance of <see cref="T:System.Security.Cryptography.HMACSHA1" />.</summary>
483+
<summary>Resets the hash algorithm to its initial state.</summary>
484484
<remarks>To be added.</remarks>
485485
</Docs>
486486
</Member>
@@ -544,10 +544,11 @@ Releases the unmanaged resources used by the <see cref="T:System.Security.Crypto
544544
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
545545
</Parameters>
546546
<Docs>
547-
<param name="destination">To be added.</param>
548-
<param name="bytesWritten">To be added.</param>
549-
<summary>To be added.</summary>
550-
<returns>To be added.</returns>
547+
<param name="destination">The buffer to receive the HMAC value.</param>
548+
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
549+
<summary>Attempts to finalize the HMAC computation after the last data is processed by the HMAC algorithm.</summary>
550+
<returns>
551+
<see langword="true"/> if <paramref name="destination"/> is long enough to receive the HMAC value; otherwise, <see langword="false"/>.</returns>
551552
<remarks>To be added.</remarks>
552553
</Docs>
553554
</Member>

‎xml/System.Security.Cryptography/HMACSHA256.xml‎

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -195,8 +195,9 @@
195195
<Parameter Name="disposing" Type="System.Boolean" Index="0" FrameworkAlternate="netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.1" />
196196
</Parameters>
197197
<Docs>
198-
<param name="disposing">To be added.</param>
199-
<summary>To be added.</summary>
198+
<param name="disposing">
199+
<see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.</param>
200+
<summary>Releases the unmanaged resources used by the <see cref="T:System.Security.Cryptography.HMACSHA256" /> and optionally releases the managed resources.</summary>
200201
<remarks>To be added.</remarks>
201202
</Docs>
202203
</Member>
@@ -226,8 +227,8 @@
226227
<Parameter Name="source" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
227228
</Parameters>
228229
<Docs>
229-
<param name="source">To be added.</param>
230-
<summary>To be added.</summary>
230+
<param name="source">The input to compute the HMAC for.</param>
231+
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
231232
<remarks>To be added.</remarks>
232233
</Docs>
233234
</Member>
@@ -263,10 +264,10 @@
263264
<Parameter Name="cb" Type="System.Int32" Index="2" FrameworkAlternate="netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.1" />
264265
</Parameters>
265266
<Docs>
266-
<param name="rgb">To be added.</param>
267-
<param name="ib">To be added.</param>
268-
<param name="cb">To be added.</param>
269-
<summary>To be added.</summary>
267+
<param name="rgb">The input to compute the HMAC for.</param>
268+
<param name="ib">The offset into the byte array from which to begin using data.</param>
269+
<param name="cb">The number of bytes in the byte array to use as data.</param>
270+
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
270271
<remarks>To be added.</remarks>
271272
</Docs>
272273
</Member>
@@ -298,8 +299,8 @@
298299
</ReturnValue>
299300
<Parameters />
300301
<Docs>
301-
<summary>To be added.</summary>
302-
<returns>To be added.</returns>
302+
<summary>Finalizes the HMAC computation after the last data is processed by the algorithm.</summary>
303+
<returns>The computed HMAC value in a byte array.</returns>
303304
<remarks>To be added.</remarks>
304305
</Docs>
305306
</Member>
@@ -327,8 +328,8 @@
327328
<ReturnType>System.Int32</ReturnType>
328329
</ReturnValue>
329330
<Docs>
330-
<summary>To be added.</summary>
331-
<value>To be added.</value>
331+
<summary>Gets the size, in bits, of the computed HMAC.</summary>
332+
<value>The size, in bits, of the computed HMAC.</value>
332333
<remarks>To be added.</remarks>
333334
</Docs>
334335
</Member>
@@ -360,7 +361,7 @@
360361
</ReturnValue>
361362
<Parameters />
362363
<Docs>
363-
<summary>To be added.</summary>
364+
<summary>Resets the hash algorithm to its initial state.</summary>
364365
<remarks>To be added.</remarks>
365366
</Docs>
366367
</Member>
@@ -391,8 +392,8 @@
391392
<ReturnType>System.Byte[]</ReturnType>
392393
</ReturnValue>
393394
<Docs>
394-
<summary>To be added.</summary>
395-
<value>To be added.</value>
395+
<summary>Gets or sets the key to use in the HMAC calculation.</summary>
396+
<value>The key to use in the HMAC calculation.</value>
396397
<remarks>To be added.</remarks>
397398
</Docs>
398399
</Member>
@@ -423,10 +424,11 @@
423424
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
424425
</Parameters>
425426
<Docs>
426-
<param name="destination">To be added.</param>
427-
<param name="bytesWritten">To be added.</param>
428-
<summary>To be added.</summary>
429-
<returns>To be added.</returns>
427+
<param name="destination">The buffer to receive the HMAC value.</param>
428+
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
429+
<summary>Attempts to finalize the HMAC computation after the last data is processed by the HMAC algorithm.</summary>
430+
<returns>
431+
<see langword="true"/> if <paramref name="destination"/> is long enough to receive the HMAC value; otherwise, <see langword="false"/>.</returns>
430432
<remarks>To be added.</remarks>
431433
</Docs>
432434
</Member>

0 commit comments

Comments
 (0)