Skip to content

Commit 5572453

Browse files
jozkeeRon Petrusha
jozkee
and
Ron Petrusha
committed
Adding documentation for System.Text APIs tergeted for 3.0 (#2875)
* Adding documentation for System.Text APIs tergeted for 3.0 * Addressing suggestions. * Apply suggestions from code review Co-Authored-By: Ron Petrusha <[email protected]>
1 parent a802b79 commit 5572453

File tree

4 files changed

+226
-49
lines changed

4 files changed

+226
-49
lines changed

‎xml/System.Text/ASCIIEncoding.xml

Lines changed: 61 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -163,10 +163,17 @@
163163
<Parameter Name="chars" Type="System.ReadOnlySpan&lt;System.Char&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
164164
</Parameters>
165165
<Docs>
166-
<param name="chars">To be added.</param>
167-
<summary>To be added.</summary>
168-
<returns>To be added.</returns>
169-
<remarks>To be added.</remarks>
166+
<param name="chars">The span that contains the set of characters to encode.</param>
167+
<summary>Calculates the number of bytes produced by encoding the specified character span.</summary>
168+
<returns>The number of bytes produced by encoding the specified character span.</returns>
169+
<remarks>
170+
<format type="text/markdown"><![CDATA[
171+
172+
## Remarks
173+
To calculate the exact size required by <xref:System.Text.ASCIIEncoding.GetBytes%2A> to store the resulting bytes, use <xref:System.Text.ASCIIEncoding.GetByteCount%2A>. To calculate the maximum size, use <xref:System.Text.ASCIIEncoding.GetMaxByteCount%2A>. The <xref:System.Text.ASCIIEncoding.GetByteCount%2A> method generally allows allocation of less memory, while the <xref:System.Text.ASCIIEncoding.GetMaxByteCount%2A> method generally executes faster.
174+
175+
]]></format>
176+
</remarks>
170177
</Docs>
171178
</Member>
172179
<Member MemberName="GetByteCount">
@@ -436,11 +443,25 @@
436443
<Parameter Name="bytes" Type="System.Span&lt;System.Byte&gt;" Index="1" FrameworkAlternate="netcore-3.0" />
437444
</Parameters>
438445
<Docs>
439-
<param name="chars">To be added.</param>
440-
<param name="bytes">To be added.</param>
441-
<summary>To be added.</summary>
442-
<returns>To be added.</returns>
443-
<remarks>To be added.</remarks>
446+
<param name="chars">The character span to encode.</param>
447+
<param name="bytes">The span to contain the resulting set of bytes.</param>
448+
<summary>Encodes the specified character span into the specified byte span.</summary>
449+
<returns>The actual number of bytes written into <paramref name="bytes" />.</returns>
450+
<remarks>
451+
<format type="text/markdown"><![CDATA[
452+
453+
## Remarks
454+
To calculate the exact size required by <xref:System.Text.ASCIIEncoding.GetBytes%2A> to store the resulting bytes, use <xref:System.Text.ASCIIEncoding.GetByteCount%2A>. To calculate the maximum size, use <xref:System.Text.ASCIIEncoding.GetMaxByteCount%2A>. The <xref:System.Text.ASCIIEncoding.GetByteCount%2A> method generally allows allocation of less memory, while the <xref:System.Text.ASCIIEncoding.GetMaxByteCount%2A> method generally executes faster.
455+
456+
Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the <xref:System.Text.Decoder> or the <xref:System.Text.Encoder> provided by the <xref:System.Text.ASCIIEncoding.GetDecoder%2A> method or the <xref:System.Text.ASCIIEncoding.GetEncoder%2A> method, respectively.
457+
458+
<xref:System.Text.ASCIIEncoding> does not provide error detection. Any Unicode character greater than `U+007F` is encoded as the ASCII question mark ("?").
459+
460+
> [!CAUTION]
461+
> For security reasons, you should use <xref:System.Text.UTF8Encoding>, <xref:System.Text.UnicodeEncoding>, or <xref:System.Text.UTF32Encoding> and enable error detection.
462+
463+
]]></format>
464+
</remarks>
444465
</Docs>
445466
</Member>
446467
<Member MemberName="GetBytes">
@@ -768,10 +789,17 @@
768789
<Parameter Name="bytes" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-3.0" />
769790
</Parameters>
770791
<Docs>
771-
<param name="bytes">To be added.</param>
772-
<summary>To be added.</summary>
773-
<returns>To be added.</returns>
774-
<remarks>To be added.</remarks>
792+
<param name="bytes">The span containing the set of bytes to decode.</param>
793+
<summary>Calculates the number of characters produced by decoding the specified byte span.</summary>
794+
<returns>The number of characters produced by decoding the specified byte span.</returns>
795+
<remarks>
796+
<format type="text/markdown"><![CDATA[
797+
798+
## Remarks
799+
To calculate the exact size required by <xref:System.Text.ASCIIEncoding.GetChars%2A> to store the resulting characters, use <xref:System.Text.ASCIIEncoding.GetCharCount%2A>. To calculate the maximum size, use <xref:System.Text.ASCIIEncoding.GetMaxCharCount%2A>. The <xref:System.Text.ASCIIEncoding.GetCharCount%2A> method generally allows allocation of less memory, while the <xref:System.Text.ASCIIEncoding.GetMaxCharCount%2A> method generally executes faster.
800+
801+
]]></format>
802+
</remarks>
775803
</Docs>
776804
</Member>
777805
<Member MemberName="GetCharCount">
@@ -969,11 +997,25 @@
969997
<Parameter Name="chars" Type="System.Span&lt;System.Char&gt;" Index="1" FrameworkAlternate="netcore-3.0" />
970998
</Parameters>
971999
<Docs>
972-
<param name="bytes">To be added.</param>
973-
<param name="chars">To be added.</param>
974-
<summary>To be added.</summary>
975-
<returns>To be added.</returns>
976-
<remarks>To be added.</remarks>
1000+
<param name="bytes">The span containing the bytes to decode.</param>
1001+
<param name="chars">The span to contain the resulting set of characters.</param>
1002+
<summary>Decodes the specified byte span into the specified character span.</summary>
1003+
<returns>The actual number of characters written into <paramref name="chars" />.</returns>
1004+
<remarks>
1005+
<format type="text/markdown"><![CDATA[
1006+
1007+
## Remarks
1008+
To calculate the exact size required by <xref:System.Text.ASCIIEncoding.GetChars%2A> to store the resulting characters, use <xref:System.Text.ASCIIEncoding.GetCharCount%2A>. To calculate the maximum size, use <xref:System.Text.ASCIIEncoding.GetMaxCharCount%2A>. The <xref:System.Text.ASCIIEncoding.GetCharCount%2A> method generally allows allocation of less memory, while the <xref:System.Text.ASCIIEncoding.GetMaxCharCount%2A> method generally executes faster.
1009+
1010+
Data to be converted, such as data read from a stream, can be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the <xref:System.Text.Decoder> or the <xref:System.Text.Encoder> provided by the <xref:System.Text.ASCIIEncoding.GetDecoder%2A> method or the <xref:System.Text.ASCIIEncoding.GetEncoder%2A> method, respectively.
1011+
1012+
<xref:System.Text.ASCIIEncoding> does not provide error detection. Any byte greater than hexadecimal `0x7F` is decoded as the Unicode question mark ("?").
1013+
1014+
> [!CAUTION]
1015+
> For security reasons, you should use <xref:System.Text.UTF8Encoding>, <xref:System.Text.UnicodeEncoding>, or <xref:System.Text.UTF32Encoding> and enable error detection.
1016+
1017+
]]></format>
1018+
</remarks>
9771019
</Docs>
9781020
</Member>
9791021
<Member MemberName="GetChars">
@@ -1583,4 +1625,4 @@
15831625
</Docs>
15841626
</Member>
15851627
</Members>
1586-
</Type>
1628+
</Type>

‎xml/System.Text/UTF32Encoding.xml

Lines changed: 33 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1762,10 +1762,39 @@
17621762
<ReturnType>System.ReadOnlySpan&lt;System.Byte&gt;</ReturnType>
17631763
</ReturnValue>
17641764
<Docs>
1765-
<summary>To be added.</summary>
1766-
<value>To be added.</value>
1767-
<remarks>To be added.</remarks>
1765+
<summary>Gets a Unicode byte order mark encoded in UTF-32 format, if this object is configured to supply one.</summary>
1766+
<value>A byte span containing the Unicode byte order mark, if this object is configured to supply one; otherwise, a default span.</value><remarks>
1767+
<format type="text/markdown"><![CDATA[
1768+
1769+
## Remarks
1770+
The <xref:System.Text.UTF32Encoding> object can provide a preamble, which is an span of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code points `U+0000` `U+FEFF`) helps the decoder determine the byte order and the transformation format, or UTF. The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal):
1771+
1772+
- Big endian byte order: `00 00 FE FF`
1773+
1774+
- Little endian byte order: `FF FE 00 00`
1775+
1776+
You can instantiate a <xref:System.Text.UTF32Encoding> object whose <xref:System.Text.UTF32Encoding.Preamble> property is a valid BOM in the following ways:
1777+
1778+
- By retrieving the <xref:System.Text.UTF32Encoding> object returned by the <xref:System.Text.Encoding.UTF32%2A?displayProperty=nameWithType> property.
1779+
1780+
- By calling the parameterless <xref:System.Text.UTF32Encoding.%23ctor> constructor to instantiate a <xref:System.Text.UTF32Encoding> object.
1781+
1782+
- By supplying `true` as the value of the `byteOrderMark` argument to the <xref:System.Text.UTF32Encoding.%23ctor%2A> and <xref:System.Text.UTF32Encoding.%23ctor%2A> constructors.
1783+
1784+
We recommend that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to the <xref:System.Text.UTF32Encoding> object, such as untagged or improperly tagged web data, or random text files stored when a business did not have international concerns or other data. Often, user problems might be avoided if data is consistently and properly tagged.
1785+
1786+
For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost.
1787+
1788+
There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended.
1789+
1790+
For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://go.microsoft.com/fwlink/?LinkId=37123).
1791+
1792+
> [!IMPORTANT]
1793+
> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. Note that the <xref:System.Text.UTF32Encoding.GetBytes%2A> method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility.
1794+
1795+
]]></format>
1796+
</remarks>
17681797
</Docs>
17691798
</Member>
17701799
</Members>
1771-
</Type>
1800+
</Type>

0 commit comments

Comments
 (0)