Skip to content

Document System.Resources.Extensions #2857

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 6 commits into from
Aug 1, 2019
Merged

Document System.Resources.Extensions #2857

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2b5a8e0
Document System.Resources.Extensions
carlossanlop Jul 29, 2019
f1b777a
suggestions by rpetrusha
carlossanlop Jul 30, 2019
95e56a8
suggestions by mairaw
carlossanlop Jul 31, 2019
1b7d0e5
small fixes
carlossanlop Jul 31, 2019
788c2e8
simplify exception
carlossanlop Jul 31, 2019
2e504ab
suggestions by ericstj
carlossanlop Aug 1, 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
24 changes: 12 additions & 12 deletions xml/System.Resources.Extensions/DeserializingResourceReader.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
</Interface>
</Interfaces>
<Docs>
<summary>To be added.</summary>
<summary>Provides APIs similar to <see cref="T:System.Resources.ResourceReader" /> that can read and deserialize resource data.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -43,8 +43,8 @@
<Parameter Name="stream" Type="System.IO.Stream" />
</Parameters>
<Docs>
<param name="stream">To be added.</param>
<summary>To be added.</summary>
<param name="stream">The input stream.</param>
<summary>Initializes a new instance of the <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> class that reads the specified resources stream.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -64,8 +64,8 @@
<Parameter Name="fileName" Type="System.String" />
</Parameters>
<Docs>
<param name="fileName">To be added.</param>
<summary>To be added.</summary>
<param name="fileName">The path and name of the resource file to be read. This parameter is not case-sensitive.</param>
<summary>Initializes a new instance of the <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> class that reads the specified named resource file.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -86,7 +86,7 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Releases all operating system resources associated with this <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> object.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -110,7 +110,7 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Releases the resources used by the <see cref="T:System.Resources.Extensions.DeserializingResourceReader" />.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -131,8 +131,8 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Returns an enumerator for this <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> object.</summary>
<returns>An enumerator for this <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> object.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -155,10 +155,10 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Returns an enumerator for this <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> object.</summary>
<returns>An enumerator for this <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> object.</returns>
<remarks>To be added.</remarks>
Copy link
Contributor

Choose a reason for hiding this comment

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

should we add the remarks here as we did in other PRs about EII?
I'll add that to the wiki as well.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Can you please provide a remark suggestion for EII?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Can we do this in a separate PR, @mairaw?

Copy link
Contributor

Choose a reason for hiding this comment

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

No problem. I've added the boilerplate text to our writing guidelines here: https://github.com/dotnet/dotnet-api-docs/wiki/Remarks#explicit-interface-implementation

</Docs>
</Member>
</Members>
</Type>
</Type>
162 changes: 117 additions & 45 deletions xml/System.Resources.Extensions/PreserializedResourceWriter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
</Interface>
</Interfaces>
<Docs>
<summary>To be added.</summary>
<summary>Provides APIs similar to <see cref="T:System.Resources.ResourceWriter" /> that can write pre-serialized resource data.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -40,9 +40,11 @@
<Parameter Name="stream" Type="System.IO.Stream" />
</Parameters>
<Docs>
<param name="stream">To be added.</param>
<summary>To be added.</summary>
<param name="stream">The output stream.</param>
<summary>Initializes a new instance of the <see cref="T:System.Resources.Extensions.PreserializedResourceWriter" /> class that writes the resources to the provided stream.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentException"><paramref name="stream" /> is not writable.</exception>
<exception cref="T:System.ArgumentNullException"><paramref name="stream" /> is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName=".ctor">
Expand All @@ -61,9 +63,10 @@
<Parameter Name="fileName" Type="System.String" />
</Parameters>
<Docs>
<param name="fileName">To be added.</param>
<summary>To be added.</summary>
<param name="fileName">The output file name.</param>
<summary>Initializes a new instance of the <see cref="T:System.Resources.Extensions.PreserializedResourceWriter" /> class that writes the resources to the specified file.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="fileName" /> is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="AddActivatorResource">
Expand All @@ -87,12 +90,22 @@
<Parameter Name="closeAfterWrite" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="name">To be added.</param>
<param name="value">To be added.</param>
<param name="typeName">To be added.</param>
<param name="closeAfterWrite">To be added.</param>
<summary>To be added.</summary>
<param name="name">The resource name.</param>
<param name="value">The value of the resource in <see cref="T:System.IO.Stream" /> form understood by the type's constructor.</param>
<param name="typeName">The assembly qualified type name of the resource.</param>
<param name="closeAfterWrite">An optional value that indicates whether, after resources have been written, the stream should be closed (<see langword="true" />) or left open (<see langword="false" />, the default value).</param>
<summary>Adds a resource of the specified type represented by a <see cref="T:System.IO.Stream" /> value that is passed to the type's constructor when reading the resource.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException"><see paramref="name" />, <see paramref="typeName" />, or <see paramref="value" /> is <see langword="null" /></exception>.

-or-

<see paramref="typeName" /> is <see langword="null" />.

-or-

<see paramref="value" /> is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentException">The object's type is <see cref="T:System.IO.Stream" />, but it is unseekable.</exception>
</Docs>
</Member>
<Member MemberName="AddBinaryFormattedResource">
Expand All @@ -115,11 +128,16 @@
<Parameter Name="typeName" Type="System.String" />
</Parameters>
<Docs>
<param name="name">To be added.</param>
<param name="value">To be added.</param>
<param name="typeName">To be added.</param>
<summary>To be added.</summary>
<param name="name">The resource name.</param>
<param name="value">A byte array containing the value of the resource in <see cref="T:System.Byte[]" /> form understood by <see cref="System.Runtime.Serialization.Formatters.Binary.BinaryFormatter" />.</param>
<param name="typeName">The optional assembly qualified type name of the resource. The default value is <see langword="null" />.</param>
<summary>Adds a resource of the specified type, represented by a byte array, that will be passed to <see cref="System.Runtime.Serialization.Formatters.Binary.BinaryFormatter" /> when reading the resource.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException"><see paramref="name" /> is <see langword="null" />.

-or-

<see paramref="value" /> is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="AddResource">
Expand All @@ -142,10 +160,20 @@
<Parameter Name="value" Type="System.Byte[]" />
</Parameters>
<Docs>
<param name="name">To be added.</param>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="name">The resource name.</param>
<param name="value">The byte array to add as a resource.</param>
<summary>Adds a byte array as a named resource to the list of resources to be written to a file.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The resources are not written until <xref:System.Resources.Extensions.PreserializedResourceWriter.Generate> is called.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The name is <see langword="null" />.</exception>
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="AddResource">
Expand All @@ -168,10 +196,21 @@
<Parameter Name="value" Type="System.Object" />
</Parameters>
<Docs>
<param name="name">To be added.</param>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="name">The resource name.</param>
<param name="value">The object to add as a resource.</param>
<summary>Adds an object as a named resource to the list of resources to be written to a file.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The resources are not written until <xref:System.Resources.Extensions.PreserializedResourceWriter.Generate> is called.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The name is <see langword="null" />.</exception>
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentException">The stream is unseekable.</exception>
</Docs>
</Member>
<Member MemberName="AddResource">
Expand All @@ -194,10 +233,20 @@
<Parameter Name="value" Type="System.String" />
</Parameters>
<Docs>
<param name="name">To be added.</param>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="name">The resource name.</param>
<param name="value">The string to add as a resource.</param>
<summary>Adds a string as a named resource to the list of resources to be written to a file.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The resources are not written until <xref:System.Resources.Extensions.PreserializedResourceWriter.Generate> is called.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The name is <see langword="null" />.</exception>
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="AddResource">
Expand All @@ -220,11 +269,19 @@
<Parameter Name="closeAfterWrite" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="name">To be added.</param>
<param name="value">To be added.</param>
<param name="closeAfterWrite">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="name">The resource name.</param>
<param name="value">The stream to add as a resource.</param>
<param name="closeAfterWrite">An optional value that indicates whether, after resources have been written, the stream should be closed (<see langword="true" />) or left open (<see langword="false" />, the default value).</param>
<summary>Adds a <see cref="T:System.IO.Stream" /> as a named resource to the list of resources to be written to a file.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The resources are not written until <xref:System.Resources.Extensions.PreserializedResourceWriter.Generate> is called.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="AddResource">
Expand All @@ -248,11 +305,17 @@
<Parameter Name="typeName" Type="System.String" />
</Parameters>
<Docs>
<param name="name">To be added.</param>
<param name="value">To be added.</param>
<param name="typeName">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="name">The resource name.</param>
<param name="value">The value of the resource in string form understood by the type's <see cref="T:System.ComponentModel.TypeConverter" />.</param>
<param name="typeName">The assembly qualified type name of the resource.</param>
<summary>Adds a resource of the specified type represented by a string value. </summary>
<remarks>
<format type="text/markdown"><![CDATA[

If the type is a primitive type, the value will be converted using <xref:System.ComponentModel.TypeConverter> by the writer to that primitive type and stored in the resources in binary format. If the type is not a primitive type, the string value will be stored in the resources as a string and converted with a <xref:System.ComponentModel.TypeConverter> for the type when reading the resource. This conversion is done to avoid activating arbitrary types during resource writing.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="AddTypeConverterResource">
Expand All @@ -276,10 +339,10 @@
<Parameter Name="typeName" Type="System.String" />
</Parameters>
<Docs>
<param name="name">To be added.</param>
<param name="value">To be added.</param>
<param name="typeName">To be added.</param>
<summary>To be added.</summary>
<param name="name">The resource name.</param>
<param name="value">A byte array containing the resource in a form understood by the type's <see cref="T:System.ComponentModel.TypeConverter" />.</param>
<param name="typeName">The assembly qualified type name of the resource.</param>
<summary>Adds a resource of the specified type represented by a byte array that is passed to the type's <see cref="T:System.ComponentModel.TypeConverter" /> when reading the resource.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -300,8 +363,9 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Calls <see cref="M:System.Resources.Extensions.PreserializedResourceWriter.Dispose" /> to dispose the resource writer.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="Dispose">
Expand All @@ -324,8 +388,9 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Calls <see cref="M:System.Resources.Extensions.PreserializedResourceWriter.Generate" /> to write out all resources to the output stream in the system default format.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="Generate">
Expand All @@ -345,9 +410,16 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<summary>Writes all resources to the output stream in the system default format.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

If an exception occurs during object serialization or during IO, the .resources file is closed and deleted, since it is most likely invalid.

]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
</Docs>
</Member>
</Members>
</Type>
</Type>