Skip to content

Commit 9f0a9dc

Browse files
bartonjsRon Petrushacarlossanlop
committed
Add missing documentation for RandomNumberGenerator types (#2868)
* Add missing documentation for RandomNumberGenerator types * Apply suggestions from code review Co-Authored-By: Ron Petrusha <[email protected]> Co-Authored-By: Carlos Sanchez Lopez <[email protected]>
1 parent 047cd73 commit 9f0a9dc

File tree

2 files changed

+59
-28
lines changed

2 files changed

+59
-28
lines changed

‎xml/System.Security.Cryptography/RNGCryptoServiceProvider.xml

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -285,8 +285,8 @@
285285
<Parameter Name="disposing" Type="System.Boolean" Index="0" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinmac-3.0" />
286286
</Parameters>
287287
<Docs>
288-
<param name="disposing">To be added.</param>
289-
<summary>To be added.</summary>
288+
<param name="disposing"><see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.</param>
289+
<summary>Releases the unmanaged resources used by the <see cref="T:System.Security.Cryptography.RNGCryptoServiceProvider" /> and optionally releases the managed resources.</summary>
290290
<remarks>To be added.</remarks>
291291
</Docs>
292292
</Member>
@@ -315,7 +315,7 @@
315315
</ReturnValue>
316316
<Parameters />
317317
<Docs>
318-
<summary>To be added.</summary>
318+
<summary>Frees resources used by the <see cref="T:System.Security.Cryptography.RNGCryptoServiceProvider"/> class.</summary>
319319
<remarks>To be added.</remarks>
320320
</Docs>
321321
</Member>
@@ -408,8 +408,8 @@
408408
<Parameter Name="data" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
409409
</Parameters>
410410
<Docs>
411-
<param name="data">To be added.</param>
412-
<summary>To be added.</summary>
411+
<param name="data">The span to fill with cryptographically strong random bytes.</param>
412+
<summary>Fills a span with cryptographically strong random bytes.</summary>
413413
<remarks>To be added.</remarks>
414414
</Docs>
415415
</Member>
@@ -440,11 +440,14 @@
440440
<Parameter Name="count" Type="System.Int32" Index="2" FrameworkAlternate="netcore-3.0" />
441441
</Parameters>
442442
<Docs>
443-
<param name="data">To be added.</param>
444-
<param name="offset">To be added.</param>
445-
<param name="count">To be added.</param>
446-
<summary>To be added.</summary>
443+
<param name="data">The array to fill with cryptographically strong random bytes.</param>
444+
<param name="offset">The index of the array to start the fill operation.</param>
445+
<param name="count">The number of bytes to fill.</param>
446+
<summary>Fills the specified byte array with a cryptographically strong random sequence of values starting at a specified index for a specified number of bytes.</summary>
447447
<remarks>To be added.</remarks>
448+
<exception cref="T:System.ArgumentNullException"><paramref name="data" /> is <see langword="null" />.</exception>
449+
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="offset" /> or <paramref name="count" /> is less than 0.</exception>
450+
<exception cref="T:System.ArgumentException"><paramref name="offset" /> plus <paramref name="count" /> exceeds the length of <paramref name="data" />.</exception>
448451
</Docs>
449452
</Member>
450453
<Member MemberName="GetNonZeroBytes">
@@ -534,10 +537,10 @@
534537
<Parameter Name="data" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
535538
</Parameters>
536539
<Docs>
537-
<param name="data">To be added.</param>
538-
<summary>To be added.</summary>
540+
<param name="data">The span to fill with cryptographically strong random nonzero bytes.</param>
541+
<summary>Fills a byte span with a cryptographically strong random sequence of nonzero values.</summary>
539542
<remarks>To be added.</remarks>
540543
</Docs>
541544
</Member>
542545
</Members>
543-
</Type>
546+
</Type>

‎xml/System.Security.Cryptography/RandomNumberGenerator.xml

Lines changed: 44 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -336,8 +336,8 @@ To create a random number generator, call the @System.Security.Cryptography.Rand
336336
<Parameter Name="data" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
337337
</Parameters>
338338
<Docs>
339-
<param name="data">To be added.</param>
340-
<summary>To be added.</summary>
339+
<param name="data">The span to fill with cryptographically strong random bytes.</param>
340+
<summary>Fills a span with cryptographically strong random bytes.</summary>
341341
<remarks>To be added.</remarks>
342342
</Docs>
343343
</Member>
@@ -408,6 +408,7 @@ To create a random number generator, call the @System.Security.Cryptography.Rand
408408
]]></format>
409409
</remarks>
410410
<related type="Article" href="~/docs/standard/security/cryptographic-services.md">Cryptographic Services</related>
411+
<altmember cref="M:System.Security.Cryptography.RandomNumberGenerator.Fill(System.Span&lt;System.Byte&gt;)"/>
411412
</Docs>
412413
</Member>
413414
<Member MemberName="GetBytes">
@@ -436,9 +437,10 @@ To create a random number generator, call the @System.Security.Cryptography.Rand
436437
<Parameter Name="data" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
437438
</Parameters>
438439
<Docs>
439-
<param name="data">To be added.</param>
440-
<summary>To be added.</summary>
440+
<param name="data">The span to fill with cryptographically strong random bytes.</param>
441+
<summary>Fills a span with cryptographically strong random bytes.</summary>
441442
<remarks>To be added.</remarks>
443+
<altmember cref="M:System.Security.Cryptography.RandomNumberGenerator.Fill(System.Span&lt;System.Byte&gt;)"/>
442444
</Docs>
443445
</Member>
444446
<Member MemberName="GetBytes">
@@ -512,10 +514,22 @@ To create a random number generator, call the @System.Security.Cryptography.Rand
512514
<Parameter Name="toExclusive" Type="System.Int32" Index="0" FrameworkAlternate="netcore-3.0;netstandard-2.1" />
513515
</Parameters>
514516
<Docs>
515-
<param name="toExclusive">To be added.</param>
516-
<summary>To be added.</summary>
517-
<returns>To be added.</returns>
518-
<remarks>To be added.</remarks>
517+
<param name="toExclusive">The exclusive upper bound of the random range.</param>
518+
<summary>Generates a random integer between 0 (inclusive) and a specified exclusive upper bound using a cryptographically strong random number generator.</summary>
519+
<returns>A random integer between 0 (inclusive) and <paramref name="toExclusive"/> (exclusive).</returns>
520+
<remarks>
521+
<format type="text/markdown"><![CDATA[
522+
523+
## Remarks
524+
525+
The upper bound is exclusive to enable passing in a length value from an array, span, or list.
526+
Because it is an exclusive upper bound this method can never generate <xref:System.Int32.MaxValue?displayProperty=nameWithType>.
527+
528+
This method uses a discard-and-retry strategy to avoid the low value bias that a simple modular arithmetic operation would produce.
529+
530+
]]></format>
531+
</remarks>
532+
<exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="toExclusive"/> parameter is less than or equal to 0.</exception>
519533
</Docs>
520534
</Member>
521535
<Member MemberName="GetInt32">
@@ -545,11 +559,25 @@ To create a random number generator, call the @System.Security.Cryptography.Rand
545559
<Parameter Name="toExclusive" Type="System.Int32" Index="1" FrameworkAlternate="netcore-3.0;netstandard-2.1" />
546560
</Parameters>
547561
<Docs>
548-
<param name="fromInclusive">To be added.</param>
549-
<param name="toExclusive">To be added.</param>
550-
<summary>To be added.</summary>
551-
<returns>To be added.</returns>
552-
<remarks>To be added.</remarks>
562+
<param name="fromInclusive">The inclusive lower bound of the random range.</param>
563+
<param name="toExclusive">The exclusive upper bound of the random range.</param>
564+
<summary>Generates a random integer between a specified inclusive lower bound and a specified exclusive upper bound using a cryptographically strong random number generator.</summary>
565+
<returns>A random integer between <paramref name="fromInclusive"/> (inclusive) and <paramref name="toExclusive"/> (exclusive).</returns>
566+
<remarks>
567+
<format type="text/markdown"><![CDATA[
568+
569+
## Remarks
570+
571+
The upper bound is exclusive to enable passing in a length value from an array, span, or list.
572+
Because it is an exclusive upper bound this method can never generate <xref:System.Int32.MaxValue?displayProperty=nameWithType>.
573+
574+
This method uses a discard-and-retry strategy to avoid the low value bias that a simple modular arithmetic operation would produce.
575+
576+
Negative values are permitted for both `fromInclusive` and `toExclusive`.
577+
578+
]]></format>
579+
</remarks>
580+
<exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="toExclusive"/> parameter is less than or equal to the <paramref name="fromInclusive"/> parameter.</exception>
553581
</Docs>
554582
</Member>
555583
<Member MemberName="GetNonZeroBytes">
@@ -632,10 +660,10 @@ To create a random number generator, call the @System.Security.Cryptography.Rand
632660
<Parameter Name="data" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
633661
</Parameters>
634662
<Docs>
635-
<param name="data">To be added.</param>
636-
<summary>To be added.</summary>
663+
<param name="data">The span to fill with cryptographically strong random nonzero bytes.</param>
664+
<summary>Fills a byte span with a cryptographically strong random sequence of nonzero values.</summary>
637665
<remarks>To be added.</remarks>
638666
</Docs>
639667
</Member>
640668
</Members>
641-
</Type>
669+
</Type>

0 commit comments

Comments
 (0)