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 1 commit
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
22 changes: 11 additions & 11 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 similar APIs to <see cref="T:System.Resources.ResourceReader" /> which allow reading deserializing 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. <c>filename</c> 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,8 +155,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>
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>
Expand Down
144 changes: 102 additions & 42 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 similar APIs to <see cref="T:System.Resources.ResourceWriter" /> which allow writing 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">Initializes a new instance of the <see cref="T:System.Resources.Extensions.PreserializedResourceWriter" /> class that writes the resources to the provided stream.</param>
<summary>The output stream.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentException">The <paramref name="stream" /> is not writable.</exception>
<exception cref="T:System.ArgumentNullException">The <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">Assembly qualified type name of the resource.</param>
<param name="closeAfterWrite">Allows to optionally indicate that the stream should be closed after resources have been written. The default value is <see langword="false" />.</param>
<summary>Adds a resource of the specified type represented by a <see cref="T:System.IO.Stream" /> value which will be passed to the type's constructor 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="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">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">Optionally indicate the 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 <see cref="T:System.Byte[]" /> value which 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">Allows to optionally indicate that the stream should be closed after resources have been written. The default value is <see langword="false" />.</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,10 +305,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">The value of the resource in string form understood by the type's <see cref="T:System.ComponentModel.TypeConverter" />.</param>
<param name="typeName">An assembly qualified type name of the resource</param>
<summary>Adds a resource of the specified type represented by a string value. If the type is a primitive type, the value will be converted using <see cref="T: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 <see cref="T:System.ComponentModel.TypeConverter" /> for the type when reading the resource. This conversion is done to avoid activating arbitrary types during resource writing.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -276,10 +333,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">The value of the resource in <see cref="T:System.Byte[]" /> form understood by the type's <see cref="T:System.ComponentModel.TypeConverter" />.</param>
<param name="typeName">Assembly qualified type name of the resource.</param>
<summary>Adds a resource of specified type represented by a <see cref="T:System.Byte[]" /> value which will be 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 +357,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 +382,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,8 +404,9 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Write out all resources to the output stream in the system default format. If an exception occurs during object serialization or during IO, the .resources file is closed and deleted, since it is most likely invalid.</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
</Docs>
</Member>
</Members>
Expand Down