Skip to content

Commit 9fdf549

Browse files
carlossanlopericstj
authored and
Ron Petrusha
committed
Document System.Resources.Extensions (#2857)
* Document System.Resources.Extensions * suggestions by rpetrusha Co-Authored-By: Ron Petrusha <[email protected]> * suggestions by mairaw Co-Authored-By: Maira Wenzel <[email protected]> * small fixes * simplify exception * suggestions by ericstj Co-Authored-By: Eric StJohn <[email protected]>
1 parent b3af898 commit 9fdf549

File tree

2 files changed

+123
-57
lines changed

2 files changed

+123
-57
lines changed

‎xml/System.Resources.Extensions/DeserializingResourceReader.xml

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
</Interface>
2525
</Interfaces>
2626
<Docs>
27-
<summary>To be added.</summary>
27+
<summary>Provides APIs similar to <see cref="T:System.Resources.ResourceReader" /> that can read and deserialize resource data written by either <see cref="T:System.Resources.ResourceWriter" /> or <see cref="T:System.Resources.Extensions.PreserializedResourceWriter" />.</summary>
2828
<remarks>To be added.</remarks>
2929
</Docs>
3030
<Members>
@@ -43,8 +43,8 @@
4343
<Parameter Name="stream" Type="System.IO.Stream" />
4444
</Parameters>
4545
<Docs>
46-
<param name="stream">To be added.</param>
47-
<summary>To be added.</summary>
46+
<param name="stream">The input stream.</param>
47+
<summary>Initializes a new instance of the <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> class that reads the specified resources stream.</summary>
4848
<remarks>To be added.</remarks>
4949
</Docs>
5050
</Member>
@@ -64,8 +64,8 @@
6464
<Parameter Name="fileName" Type="System.String" />
6565
</Parameters>
6666
<Docs>
67-
<param name="fileName">To be added.</param>
68-
<summary>To be added.</summary>
67+
<param name="fileName">The path and name of the resource file to be read.</param>
68+
<summary>Initializes a new instance of the <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> class that reads the specified named resource file.</summary>
6969
<remarks>To be added.</remarks>
7070
</Docs>
7171
</Member>
@@ -86,7 +86,7 @@
8686
</ReturnValue>
8787
<Parameters />
8888
<Docs>
89-
<summary>To be added.</summary>
89+
<summary>Releases all operating system resources associated with this <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> object.</summary>
9090
<remarks>To be added.</remarks>
9191
</Docs>
9292
</Member>
@@ -110,7 +110,7 @@
110110
</ReturnValue>
111111
<Parameters />
112112
<Docs>
113-
<summary>To be added.</summary>
113+
<summary>Releases the resources used by the <see cref="T:System.Resources.Extensions.DeserializingResourceReader" />.</summary>
114114
<remarks>To be added.</remarks>
115115
</Docs>
116116
</Member>
@@ -131,8 +131,8 @@
131131
</ReturnValue>
132132
<Parameters />
133133
<Docs>
134-
<summary>To be added.</summary>
135-
<returns>To be added.</returns>
134+
<summary>Returns an enumerator for this <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> object.</summary>
135+
<returns>An enumerator for this <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> object.</returns>
136136
<remarks>To be added.</remarks>
137137
</Docs>
138138
</Member>
@@ -155,10 +155,10 @@
155155
</ReturnValue>
156156
<Parameters />
157157
<Docs>
158-
<summary>To be added.</summary>
159-
<returns>To be added.</returns>
158+
<summary>Returns an enumerator for this <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> object.</summary>
159+
<returns>An enumerator for this <see cref="T:System.Resources.Extensions.DeserializingResourceReader" /> object.</returns>
160160
<remarks>To be added.</remarks>
161161
</Docs>
162162
</Member>
163163
</Members>
164-
</Type>
164+
</Type>

‎xml/System.Resources.Extensions/PreserializedResourceWriter.xml

Lines changed: 111 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
</Interface>
2222
</Interfaces>
2323
<Docs>
24-
<summary>To be added.</summary>
24+
<summary>Provides APIs similar to <see cref="T:System.Resources.ResourceWriter" /> that can write pre-serialized resource data.</summary>
2525
<remarks>To be added.</remarks>
2626
</Docs>
2727
<Members>
@@ -40,9 +40,11 @@
4040
<Parameter Name="stream" Type="System.IO.Stream" />
4141
</Parameters>
4242
<Docs>
43-
<param name="stream">To be added.</param>
44-
<summary>To be added.</summary>
43+
<param name="stream">The output stream.</param>
44+
<summary>Initializes a new instance of the <see cref="T:System.Resources.Extensions.PreserializedResourceWriter" /> class that writes the resources to the provided stream.</summary>
4545
<remarks>To be added.</remarks>
46+
<exception cref="T:System.ArgumentException"><paramref name="stream" /> is not writable.</exception>
47+
<exception cref="T:System.ArgumentNullException"><paramref name="stream" /> is <see langword="null" />.</exception>
4648
</Docs>
4749
</Member>
4850
<Member MemberName=".ctor">
@@ -61,9 +63,10 @@
6163
<Parameter Name="fileName" Type="System.String" />
6264
</Parameters>
6365
<Docs>
64-
<param name="fileName">To be added.</param>
65-
<summary>To be added.</summary>
66+
<param name="fileName">The output file name.</param>
67+
<summary>Initializes a new instance of the <see cref="T:System.Resources.Extensions.PreserializedResourceWriter" /> class that writes the resources to the specified file.</summary>
6668
<remarks>To be added.</remarks>
69+
<exception cref="T:System.ArgumentNullException">The <paramref name="fileName" /> is <see langword="null" />.</exception>
6770
</Docs>
6871
</Member>
6972
<Member MemberName="AddActivatorResource">
@@ -87,12 +90,14 @@
8790
<Parameter Name="closeAfterWrite" Type="System.Boolean" />
8891
</Parameters>
8992
<Docs>
90-
<param name="name">To be added.</param>
91-
<param name="value">To be added.</param>
92-
<param name="typeName">To be added.</param>
93-
<param name="closeAfterWrite">To be added.</param>
94-
<summary>To be added.</summary>
93+
<param name="name">The resource name.</param>
94+
<param name="value">The value of the resource in <see cref="T:System.IO.Stream" /> form understood by the type's constructor.</param>
95+
<param name="typeName">The assembly qualified type name of the resource.</param>
96+
<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>
97+
<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>
9598
<remarks>To be added.</remarks>
99+
<exception cref="T:System.ArgumentNullException"><see paramref="name" />, <see paramref="typeName" />, or <see paramref="value" /> is <see langword="null" />.</exception>
100+
<exception cref="T:System.ArgumentException">The object's type is <see cref="T:System.IO.Stream" />, but it is unseekable.</exception>
96101
</Docs>
97102
</Member>
98103
<Member MemberName="AddBinaryFormattedResource">
@@ -115,11 +120,12 @@
115120
<Parameter Name="typeName" Type="System.String" />
116121
</Parameters>
117122
<Docs>
118-
<param name="name">To be added.</param>
119-
<param name="value">To be added.</param>
120-
<param name="typeName">To be added.</param>
121-
<summary>To be added.</summary>
123+
<param name="name">The resource name.</param>
124+
<param name="value">A byte array containing the value of the resource in <see cref="T:System.Byte[]" /> form understood by <see cref="T:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter" />.</param>
125+
<param name="typeName">The optional assembly qualified type name of the resource. The default value is <see langword="null" />.</param>
126+
<summary>Adds a resource of the specified type, represented by a byte array, that will be passed to <see cref="T:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter" /> when reading the resource.</summary>
122127
<remarks>To be added.</remarks>
128+
<exception cref="T:System.ArgumentNullException"><see paramref="name" /> or <see paramref="value" /> is <see langword="null" />.</exception>
123129
</Docs>
124130
</Member>
125131
<Member MemberName="AddResource">
@@ -142,10 +148,20 @@
142148
<Parameter Name="value" Type="System.Byte[]" />
143149
</Parameters>
144150
<Docs>
145-
<param name="name">To be added.</param>
146-
<param name="value">To be added.</param>
147-
<summary>To be added.</summary>
148-
<remarks>To be added.</remarks>
151+
<param name="name">The resource name.</param>
152+
<param name="value">The byte array to add as a resource.</param>
153+
<summary>Adds a byte array as a named resource to the list of resources to be written to a file.</summary>
154+
<remarks>
155+
<format type="text/markdown"><![CDATA[
156+
157+
## Remarks
158+
159+
The resources are not written until <xref:System.Resources.Extensions.PreserializedResourceWriter.Generate> is called.
160+
161+
]]></format>
162+
</remarks>
163+
<exception cref="T:System.ArgumentNullException">The name is <see langword="null" />.</exception>
164+
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
149165
</Docs>
150166
</Member>
151167
<Member MemberName="AddResource">
@@ -168,10 +184,21 @@
168184
<Parameter Name="value" Type="System.Object" />
169185
</Parameters>
170186
<Docs>
171-
<param name="name">To be added.</param>
172-
<param name="value">To be added.</param>
173-
<summary>To be added.</summary>
174-
<remarks>To be added.</remarks>
187+
<param name="name">The resource name.</param>
188+
<param name="value">The object to add as a resource.</param>
189+
<summary>Adds an object as a named resource to the list of resources to be written to a file.</summary>
190+
<remarks>
191+
<format type="text/markdown"><![CDATA[
192+
193+
## Remarks
194+
195+
The resources are not written until <xref:System.Resources.Extensions.PreserializedResourceWriter.Generate> is called.
196+
197+
]]></format>
198+
</remarks>
199+
<exception cref="T:System.ArgumentNullException">The name is <see langword="null" />.</exception>
200+
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
201+
<exception cref="T:System.ArgumentException">The stream is unseekable.</exception>
175202
</Docs>
176203
</Member>
177204
<Member MemberName="AddResource">
@@ -194,10 +221,20 @@
194221
<Parameter Name="value" Type="System.String" />
195222
</Parameters>
196223
<Docs>
197-
<param name="name">To be added.</param>
198-
<param name="value">To be added.</param>
199-
<summary>To be added.</summary>
200-
<remarks>To be added.</remarks>
224+
<param name="name">The resource name.</param>
225+
<param name="value">The string to add as a resource.</param>
226+
<summary>Adds a string as a named resource to the list of resources to be written to a file.</summary>
227+
<remarks>
228+
<format type="text/markdown"><![CDATA[
229+
230+
## Remarks
231+
232+
The resources are not written until <xref:System.Resources.Extensions.PreserializedResourceWriter.Generate> is called.
233+
234+
]]></format>
235+
</remarks>
236+
<exception cref="T:System.ArgumentNullException">The name is <see langword="null" />.</exception>
237+
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
201238
</Docs>
202239
</Member>
203240
<Member MemberName="AddResource">
@@ -220,11 +257,19 @@
220257
<Parameter Name="closeAfterWrite" Type="System.Boolean" />
221258
</Parameters>
222259
<Docs>
223-
<param name="name">To be added.</param>
224-
<param name="value">To be added.</param>
225-
<param name="closeAfterWrite">To be added.</param>
226-
<summary>To be added.</summary>
227-
<remarks>To be added.</remarks>
260+
<param name="name">The resource name.</param>
261+
<param name="value">The stream to add as a resource.</param>
262+
<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>
263+
<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>
264+
<remarks>
265+
<format type="text/markdown"><![CDATA[
266+
267+
## Remarks
268+
269+
The resources are not written until <xref:System.Resources.Extensions.PreserializedResourceWriter.Generate> is called.
270+
271+
]]></format>
272+
</remarks>
228273
</Docs>
229274
</Member>
230275
<Member MemberName="AddResource">
@@ -248,11 +293,19 @@
248293
<Parameter Name="typeName" Type="System.String" />
249294
</Parameters>
250295
<Docs>
251-
<param name="name">To be added.</param>
252-
<param name="value">To be added.</param>
253-
<param name="typeName">To be added.</param>
254-
<summary>To be added.</summary>
255-
<remarks>To be added.</remarks>
296+
<param name="name">The resource name.</param>
297+
<param name="value">The value of the resource in string form understood by the type's <see cref="T:System.ComponentModel.TypeConverter" />.</param>
298+
<param name="typeName">The assembly qualified type name of the resource.</param>
299+
<summary>Adds a resource of the specified type represented by a string value. </summary>
300+
<remarks>
301+
<format type="text/markdown"><![CDATA[
302+
303+
## Remarks
304+
305+
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.
306+
307+
]]></format>
308+
</remarks>
256309
</Docs>
257310
</Member>
258311
<Member MemberName="AddTypeConverterResource">
@@ -276,10 +329,10 @@
276329
<Parameter Name="typeName" Type="System.String" />
277330
</Parameters>
278331
<Docs>
279-
<param name="name">To be added.</param>
280-
<param name="value">To be added.</param>
281-
<param name="typeName">To be added.</param>
282-
<summary>To be added.</summary>
332+
<param name="name">The resource name.</param>
333+
<param name="value">A byte array containing the resource in a form understood by the type's <see cref="T:System.ComponentModel.TypeConverter" />.</param>
334+
<param name="typeName">The assembly qualified type name of the resource.</param>
335+
<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>
283336
<remarks>To be added.</remarks>
284337
</Docs>
285338
</Member>
@@ -300,8 +353,9 @@
300353
</ReturnValue>
301354
<Parameters />
302355
<Docs>
303-
<summary>To be added.</summary>
356+
<summary>Calls <see cref="M:System.Resources.Extensions.PreserializedResourceWriter.Dispose" /> to dispose the resource writer.</summary>
304357
<remarks>To be added.</remarks>
358+
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
305359
</Docs>
306360
</Member>
307361
<Member MemberName="Dispose">
@@ -324,8 +378,9 @@
324378
</ReturnValue>
325379
<Parameters />
326380
<Docs>
327-
<summary>To be added.</summary>
381+
<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>
328382
<remarks>To be added.</remarks>
383+
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
329384
</Docs>
330385
</Member>
331386
<Member MemberName="Generate">
@@ -345,9 +400,20 @@
345400
</ReturnValue>
346401
<Parameters />
347402
<Docs>
348-
<summary>To be added.</summary>
349-
<remarks>To be added.</remarks>
403+
<summary>Writes all resources to the output stream.</summary>
404+
<remarks>
405+
<format type="text/markdown"><![CDATA[
406+
407+
## Remarks
408+
409+
If the resources added to the writer can be represented in the system default format understood by the <xref:System.Resources.ResourceReader>, they will be written as such. If the resources require runtime deserialization other than that supported by the system default format (<xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter>) then we will write them using the format understood by <xref:System.Resources.Extensions.DeserializingResourceReader>.
410+
411+
If an exception occurs during object serialization or during IO, the .resources file is closed and deleted, since it is most likely invalid.
412+
413+
]]></format>
414+
</remarks>
415+
<exception cref="T:System.InvalidOperationException">The resource list is <see langword="null" />.</exception>
350416
</Docs>
351417
</Member>
352418
</Members>
353-
</Type>
419+
</Type>

0 commit comments

Comments
 (0)