Skip to content

Add missing, and update existing, documentation on the HashAlgorithm classes. #3617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 5, 2019
+214 −155
Merged

Add missing, and update existing, documentation on the HashAlgorithm classes. #3617

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7a0e2cf
Add missing, and update existing, documentation on the HashAlgorithm …
bartonjs Dec 3, 2019
ea73b9a
Apply suggestions from code review
bartonjs Dec 3, 2019
f4fd4dc
Apply suggestions from code review
bartonjs Dec 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 36 additions & 15 deletions xml/System.Security.Cryptography/HMAC.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,9 +346,20 @@
<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" />
</Parameters>
<Docs>
<param name="source">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="source">The input to compute the HMAC code for.</param>
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The default implementation of this method throws a <xref:System.PlatformNotSupportedException>
because there is no managed implementation of HMAC.

Derived types must override this method.

]]></format>
</remarks>
<exception cref="T:System.PlatformNotSupportedException">In all cases.</exception>
</Docs>
</Member>
<Member MemberName="HashCore">
Expand Down Expand Up @@ -388,15 +399,13 @@
<param name="rgb">The input data.</param>
<param name="ib">The offset into the byte array from which to begin using data.</param>
<param name="cb">The number of bytes in the array to use as data.</param>
<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>
<summary>When overridden in a derived class, routes data written to the object into the HMAC algorithm for computing the HMAC value.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method is not called by application code.

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.

]]></format>
</remarks>
<altmember cref="T:System.Security.Cryptography.HashAlgorithm" />
Expand Down Expand Up @@ -433,8 +442,8 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>When overridden in a derived class, finalizes the hash computation after the last data is processed by the cryptographic stream object.</summary>
<returns>The computed hash code in a byte array.</returns>
<summary>When overridden in a derived class, finalizes the HMAC computation after the last data is processed by the algorithm.</summary>
<returns>The computed HMAC value in a byte array.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

Expand Down Expand Up @@ -562,8 +571,8 @@
<ReturnType>System.Byte[]</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets or sets the key to use in the hash algorithm.</summary>
<value>The key to use in the hash algorithm.</value>
<summary>Gets or sets the key to use in the HMAC calculation.</summary>
<value>The key to use in the HMAC calculation.</value>
<remarks>
<format type="text/markdown"><![CDATA[

Expand Down Expand Up @@ -611,11 +620,23 @@
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
<param name="destination">To be added.</param>
<param name="bytesWritten">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="destination">The buffer to receive the HMAC value.</param>
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
<summary>Attempts to finalize the HMAC computation after the last data is processed by the HMAC algorithm.</summary>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<summary>Attempts to finalize the HMAC computation after the last data is processed by the HMAC algorithm.</summary>
<summary>Throws a <see cref="T:System.PlatformNotSupportedException" /> in all cases.</summary>

<returns>
<see langword="true"/> if <paramref name="destination"/> is long enough to receive the HMAC value; otherwise, <see langword="false"/>.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The default implementation of this method throws a <xref:System.PlatformNotSupportedException>
because there is no managed implementation of HMAC.

Derived types must override this method.

]]></format>
</remarks>
<exception cref="T:System.PlatformNotSupportedException">The method is not overriden in the derived type.</exception>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<exception cref="T:System.PlatformNotSupportedException">The method is not overriden in the derived type.</exception>
<exception cref="T:System.PlatformNotSupportedException">In all cases.</exception>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this suggestion is accurate. The method will not throw if the derived class implements it.

</Docs>
</Member>
</Members>
Expand Down
40 changes: 21 additions & 19 deletions xml/System.Security.Cryptography/HMACMD5.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,8 +199,9 @@
<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" />
</Parameters>
<Docs>
<param name="disposing">To be added.</param>
<summary>To be added.</summary>
<param name="disposing">
<see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.</param>
<summary>Releases the unmanaged resources used by the <see cref="T:System.Security.Cryptography.HMACMD5" /> and optionally releases the managed resources.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -230,8 +231,8 @@
<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" />
</Parameters>
<Docs>
<param name="source">To be added.</param>
<summary>To be added.</summary>
<param name="source">The input to compute the HMAC for.</param>
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -267,10 +268,10 @@
<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" />
</Parameters>
<Docs>
<param name="rgb">To be added.</param>
<param name="ib">To be added.</param>
<param name="cb">To be added.</param>
<summary>To be added.</summary>
<param name="rgb">The input to compute the HMAC for.</param>
<param name="ib">The offset into the byte array from which to begin using data.</param>
<param name="cb">The number of bytes in the byte array to use as data.</param>
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -302,8 +303,8 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Finalizes the HMAC computation after the last data is processed by the algorithm.</summary>
<returns>The computed HMAC value in a byte array.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -331,8 +332,8 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the size, in bits, of the computed HMAC.</summary>
<value>The size, in bits, of the computed HMAC.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -364,7 +365,7 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Resets the hash algorithm to its initial state.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -395,8 +396,8 @@
<ReturnType>System.Byte[]</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets or sets the key to use in the HMAC calculation.</summary>
<value>The key to use in the HMAC calculation.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -427,10 +428,11 @@
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
<param name="destination">To be added.</param>
<param name="bytesWritten">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="destination">The buffer to receive the HMAC value.</param>
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
<summary>Attempts to finalize the HMAC computation after the last data is processed by the HMAC algorithm.</summary>
<returns>
<see langword="true"/> if <paramref name="destination"/> is long enough to receive the HMAC value; otherwise, <see langword="false"/>.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
23 changes: 12 additions & 11 deletions xml/System.Security.Cryptography/HMACSHA1.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -316,8 +316,8 @@ Releases the unmanaged resources used by the <see cref="T:System.Security.Crypto
<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" />
</Parameters>
<Docs>
<param name="source">To be added.</param>
<summary>To be added.</summary>
<param name="source">The input to compute the HMAC for.</param>
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -390,8 +390,8 @@ Releases the unmanaged resources used by the <see cref="T:System.Security.Crypto
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Finalizes the HMAC computation after the last data is processed by the algorithm.</summary>
<returns>The computed HMAC value in a byte array.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -446,8 +446,8 @@ Releases the unmanaged resources used by the <see cref="T:System.Security.Crypto
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the size, in bits, of the computed HMAC.</summary>
<value>The size, in bits, of the computed HMAC.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -480,7 +480,7 @@ Releases the unmanaged resources used by the <see cref="T:System.Security.Crypto
</ReturnValue>
<Parameters />
<Docs>
<summary>Initializes an instance of <see cref="T:System.Security.Cryptography.HMACSHA1" />.</summary>
<summary>Resets the hash algorithm to its initial state.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -544,10 +544,11 @@ Releases the unmanaged resources used by the <see cref="T:System.Security.Crypto
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
<param name="destination">To be added.</param>
<param name="bytesWritten">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="destination">The buffer to receive the HMAC value.</param>
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
<summary>Attempts to finalize the HMAC computation after the last data is processed by the HMAC algorithm.</summary>
<returns>
<see langword="true"/> if <paramref name="destination"/> is long enough to receive the HMAC value; otherwise, <see langword="false"/>.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
40 changes: 21 additions & 19 deletions xml/System.Security.Cryptography/HMACSHA256.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,8 +195,9 @@
<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" />
</Parameters>
<Docs>
<param name="disposing">To be added.</param>
<summary>To be added.</summary>
<param name="disposing">
<see langword="true" /> to release both managed and unmanaged resources; <see langword="false" /> to release only unmanaged resources.</param>
<summary>Releases the unmanaged resources used by the <see cref="T:System.Security.Cryptography.HMACSHA256" /> and optionally releases the managed resources.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -226,8 +227,8 @@
<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" />
</Parameters>
<Docs>
<param name="source">To be added.</param>
<summary>To be added.</summary>
<param name="source">The input to compute the HMAC for.</param>
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -263,10 +264,10 @@
<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" />
</Parameters>
<Docs>
<param name="rgb">To be added.</param>
<param name="ib">To be added.</param>
<param name="cb">To be added.</param>
<summary>To be added.</summary>
<param name="rgb">The input to compute the HMAC for.</param>
<param name="ib">The offset into the byte array from which to begin using data.</param>
<param name="cb">The number of bytes in the byte array to use as data.</param>
<summary>Routes data written to the object into the HMAC algorithm for computing the HMAC.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -298,8 +299,8 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Finalizes the HMAC computation after the last data is processed by the algorithm.</summary>
<returns>The computed HMAC value in a byte array.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -327,8 +328,8 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets the size, in bits, of the computed HMAC.</summary>
<value>The size, in bits, of the computed HMAC.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -360,7 +361,7 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Resets the hash algorithm to its initial state.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -391,8 +392,8 @@
<ReturnType>System.Byte[]</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets or sets the key to use in the HMAC calculation.</summary>
<value>The key to use in the HMAC calculation.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -423,10 +424,11 @@
<Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
<param name="destination">To be added.</param>
<param name="bytesWritten">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="destination">The buffer to receive the HMAC value.</param>
<param name="bytesWritten">When this method returns, the total number of bytes written into <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
<summary>Attempts to finalize the HMAC computation after the last data is processed by the HMAC algorithm.</summary>
<returns>
<see langword="true"/> if <paramref name="destination"/> is long enough to receive the HMAC value; otherwise, <see langword="false"/>.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
Loading