Skip to content

Commit e51d16c

Browse files
StephenMolloycarlossanlopBillWagnermairaw
committed
Update docs for new Syndication APIs in 2.x (#3743)
* Update docs for new Syndication APIs in 2.x * Apply suggestions from code review Resolve CI warnings. Co-Authored-By: Carlos Sanchez Lopez <[email protected]> * Apply suggestions from code review Some text and formatting cleanup from review. Co-Authored-By: Bill Wagner <[email protected]> * More formatting updates from review. * More review feedback. * Fix broken build build due to missing '/'. Co-Authored-By: Maira Wenzel <[email protected]> * Update xml/System.ServiceModel.Syndication/SyndicationFeed.xml Co-Authored-By: Carlos Sanchez Lopez <[email protected]> Co-authored-by: Carlos Sanchez Lopez <[email protected]> Co-authored-by: Bill Wagner <[email protected]> Co-authored-by: Maira Wenzel <[email protected]>
1 parent 6cbdf22 commit e51d16c

File tree

7 files changed

+228
-77
lines changed

7 files changed

+228
-77
lines changed

‎xml/System.ServiceModel.Syndication/SyndicationFeed.xml

Lines changed: 91 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1082,9 +1082,16 @@
10821082
<ReturnType>System.ServiceModel.Syndication.SyndicationLink</ReturnType>
10831083
</ReturnValue>
10841084
<Docs>
1085-
<summary>To be added.</summary>
1086-
<value>To be added.</value>
1087-
<remarks>To be added.</remarks>
1085+
<summary>Gets or sets the link to documentation for the feed.</summary>
1086+
<value>A <see cref="T:System.ServiceModel.Syndication.SyndicationLink" /> instance that contains a link to documentation for the feed.</value>
1087+
<remarks>
1088+
<format type="text/markdown"><![CDATA[
1089+
1090+
## Remarks
1091+
When serialized to RSS 2.0, the <xref:System.ServiceModel.Syndication.SyndicationFeed.Documentation%2A> property is written to a `<docs>` element.
1092+
1093+
]]></format>
1094+
</remarks>
10881095
</Docs>
10891096
</Member>
10901097
<Member MemberName="ElementExtensions">
@@ -1231,7 +1238,6 @@
12311238
<Docs>
12321239
<summary>Gets an <see cref="T:System.ServiceModel.Syndication.Atom10FeedFormatter" /> instance.</summary>
12331240
<returns>An <see cref="T:System.ServiceModel.Syndication.Atom10FeedFormatter" /> instance.</returns>
1234-
<remarks>To be added.</remarks>
12351241
</Docs>
12361242
</Member>
12371243
<MemberGroup MemberName="GetRss20Formatter">
@@ -1278,7 +1284,6 @@
12781284
<Docs>
12791285
<summary>Gets an <see cref="T:System.ServiceModel.Syndication.Rss20FeedFormatter" /> instance.</summary>
12801286
<returns>An <see cref="T:System.ServiceModel.Syndication.Rss20FeedFormatter" /> instance.</returns>
1281-
<remarks>To be added.</remarks>
12821287
</Docs>
12831288
</Member>
12841289
<Member MemberName="GetRss20Formatter">
@@ -1924,9 +1929,30 @@
19241929
<ReturnType>System.Collections.ObjectModel.Collection&lt;System.String&gt;</ReturnType>
19251930
</ReturnValue>
19261931
<Docs>
1927-
<summary>To be added.</summary>
1928-
<value>To be added.</value>
1929-
<remarks>To be added.</remarks>
1932+
<summary>Gets a collection of strings indicating the set of values in the 'skipDays' element for the feed.</summary>
1933+
<value>A collection of strings indicating the days when aggregators should skip updating the feed.</value>
1934+
<remarks>
1935+
<format type="text/markdown"><![CDATA[
1936+
1937+
## Remarks
1938+
When serialized to RSS 2.0, the <xref:System.ServiceModel.Syndication.SyndicationFeed.SkipDays%2A> property is written to a `<skipDays>` element
1939+
with subelements for each day in the collection.
1940+
1941+
1942+
## Examples
1943+
The following XML shows how <xref:System.ServiceModel.Syndication.SyndicationFeed.SkipHours%2A> is serialized to RSS 2.0.
1944+
1945+
```xml
1946+
<item>
1947+
<skipDays>
1948+
<day>Saturday</day>
1949+
<day>Sunday</day>
1950+
<day>Wednesday</day>
1951+
</skipDays>
1952+
</item>
1953+
```
1954+
]]></format>
1955+
</remarks>
19301956
</Docs>
19311957
</Member>
19321958
<Member MemberName="SkipHours">
@@ -1953,9 +1979,41 @@
19531979
<ReturnType>System.Collections.ObjectModel.Collection&lt;System.Int32&gt;</ReturnType>
19541980
</ReturnValue>
19551981
<Docs>
1956-
<summary>To be added.</summary>
1957-
<value>To be added.</value>
1958-
<remarks>To be added.</remarks>
1982+
<summary>Gets a collection of integers indicating the set of values in the 'skipHours' element for the feed.</summary>
1983+
<value>A collection of integer numbers indicating the hours where aggregators should skip updating the feed.</value>
1984+
<remarks>
1985+
<format type="text/markdown"><![CDATA[
1986+
1987+
## Remarks
1988+
When serialized to RSS 2.0, the <xref:System.ServiceModel.Syndication.SyndicationFeed.SkipHours%2A> property is written to a `<skipHours>` element
1989+
with subelements for each integer in the collection. Valid integer values are between 0 and 23 inclusive.
1990+
1991+
1992+
## Examples
1993+
The following XML shows how <xref:System.ServiceModel.Syndication.SyndicationFeed.SkipHours%2A> is serialized to RSS 2.0.
1994+
1995+
```xml
1996+
<item>
1997+
<skipHours>
1998+
<hour>0</hour>
1999+
<hour>1</hour>
2000+
<hour>2</hour>
2001+
<hour>3</hour>
2002+
<hour>4</hour>
2003+
<hour>5</hour>
2004+
<hour>6</hour>
2005+
<hour>7</hour>
2006+
<hour>18</hour>
2007+
<hour>19</hour>
2008+
<hour>20</hour>
2009+
<hour>21</hour>
2010+
<hour>22</hour>
2011+
<hour>23</hour>
2012+
</skipHours>
2013+
</item>
2014+
```
2015+
]]></format>
2016+
</remarks>
19592017
</Docs>
19602018
</Member>
19612019
<Member MemberName="TextInput">
@@ -1982,9 +2040,18 @@
19822040
<ReturnType>System.ServiceModel.Syndication.SyndicationTextInput</ReturnType>
19832041
</ReturnValue>
19842042
<Docs>
1985-
<summary>To be added.</summary>
1986-
<value>To be added.</value>
1987-
<remarks>To be added.</remarks>
2043+
<summary>Gets or sets the TextInput property for the feed.</summary>
2044+
<value>A <see cref="T:System.ServiceModel.Syndication.SyndicationTextInput" /> instance that contains required parameters for the RSS <c>textInput</c> item for the feed.</value>
2045+
<remarks>
2046+
<format type="text/markdown"><![CDATA[
2047+
2048+
## Remarks
2049+
The RSS specification allows for a `textInput` item to be included within a syndication feed that the publisher can use
2050+
to direct search requests or obtain feedback through a simple text input box and button. See <xref:System.ServiceModel.Syndication.SyndicationTextInput>
2051+
for more detail. If the `textInput` element is incomplete, malformed, or missing, then <xref:System.ServiceModel.Syndication.SyndicationFeed.TextInput%2A> will be `null`.
2052+
2053+
]]></format>
2054+
</remarks>
19882055
</Docs>
19892056
</Member>
19902057
<Member MemberName="TimeToLive">
@@ -2011,9 +2078,16 @@
20112078
<ReturnType>System.Nullable&lt;System.TimeSpan&gt;</ReturnType>
20122079
</ReturnValue>
20132080
<Docs>
2014-
<summary>To be added.</summary>
2015-
<value>To be added.</value>
2016-
<remarks>To be added.</remarks>
2081+
<summary>Gets or sets the 'ttl' attribute for the feed.</summary>
2082+
<value>A integer number indicating the number of minutes the feed can stay cached before refreshing it from the source.</value>
2083+
<remarks>
2084+
<format type="text/markdown"><![CDATA[
2085+
2086+
## Remarks
2087+
When serialized to RSS 2.0, the <xref:System.ServiceModel.Syndication.SyndicationFeed.TimeToLive%2A> property is written to a `<ttl>` element.
2088+
2089+
]]></format>
2090+
</remarks>
20172091
</Docs>
20182092
</Member>
20192093
<Member MemberName="Title">

‎xml/System.ServiceModel.Syndication/SyndicationFeedFormatter.xml

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -556,9 +556,16 @@
556556
<ReturnType>System.ServiceModel.Syndication.TryParseDateTimeCallback</ReturnType>
557557
</ReturnValue>
558558
<Docs>
559-
<summary>To be added.</summary>
560-
<value>To be added.</value>
561-
<remarks>To be added.</remarks>
559+
<summary>Delegate that is used by the <see cref="T:System.ServiceModel.Syndication.SyndicationFeedFormatter" /> class for converting <see cref="T:System.ServiceModel.Syndication.XmlDateTimeData" /> string data to <see cref="T:System.DateTimeOffset" />.</summary>
560+
<value>The <see cref="T:System.ServiceModel.Syndication.TryParseDateTimeCallback" /> that is used for converting string data from <see cref="T:System.ServiceModel.Syndication.XmlDateTimeData" /> to a <see cref="T:System.DateTimeOffset" /> instance.</value>
561+
<remarks>
562+
<format type="text/markdown"><![CDATA[
563+
564+
## Remarks
565+
The default callback is specific to each implementation of <xref:System.ServiceModel.Syndication.SyndicationFeedFormatter>.
566+
567+
]]></format>
568+
</remarks>
562569
</Docs>
563570
</Member>
564571
<Member MemberName="Feed">
@@ -1558,9 +1565,16 @@
15581565
<ReturnType>System.ServiceModel.Syndication.TryParseUriCallback</ReturnType>
15591566
</ReturnValue>
15601567
<Docs>
1561-
<summary>To be added.</summary>
1562-
<value>To be added.</value>
1563-
<remarks>To be added.</remarks>
1568+
<summary>Delegate that is used by the <see cref="T:System.ServiceModel.Syndication.SyndicationFeedFormatter" /> class for creating <see cref="T:System.Uri" /> instances from string input.</summary>
1569+
<value>The <see cref="T:System.ServiceModel.Syndication.TryParseUriCallback" /> that is used for creating Uri instances from string input.</value>
1570+
<remarks>
1571+
<format type="text/markdown"><![CDATA[
1572+
1573+
## Remarks
1574+
The default callback leverages <xref:System.Uri.%23ctor%2A> contructor to parse the given string into a <xref:System.Uri> object.
1575+
1576+
]]></format>
1577+
</remarks>
15641578
</Docs>
15651579
</Member>
15661580
<Member MemberName="Version">

‎xml/System.ServiceModel.Syndication/SyndicationTextInput.xml

Lines changed: 72 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,37 @@
1616
</Base>
1717
<Interfaces />
1818
<Docs>
19-
<summary>To be added.</summary>
20-
<remarks>To be added.</remarks>
19+
<summary>Represents a "textInput" entry from an RSS syndication feed.</summary>
20+
<remarks>
21+
<format type="text/markdown"><![CDATA[
22+
23+
## Remarks
24+
The RSS specification allows for a 'textInput' item to be included within a syndication feed that the publisher can use
25+
to direct search requests or obtain feedback through a simple text input box and button. A 'textInput' element in an RSS feed
26+
must contain 4 sub-elements:
27+
- title
28+
- description
29+
- name
30+
- link
31+
32+
See the [RSS spec](https://cyber.harvard.edu/rss/rss.html#lttextinputgtSubelementOfLtchannelgt)
33+
for more detail.
34+
35+
36+
37+
## Examples
38+
The following XML shows how <xref:System.ServiceModel.Syndication.SyndicationTextInput> is serialized to RSS 2.0.
39+
40+
```xml
41+
<textinput>
42+
<description>Search The Web</description>
43+
<title>Search</title>
44+
<link>http://link.to.search.engine/search?</link>
45+
<name>q</name>
46+
</textinput>
47+
```
48+
]]></format>
49+
</remarks>
2150
</Docs>
2251
<Members>
2352
<Member MemberName=".ctor">
@@ -35,8 +64,7 @@
3564
</AssemblyInfo>
3665
<Parameters />
3766
<Docs>
38-
<summary>To be added.</summary>
39-
<remarks>To be added.</remarks>
67+
<summary>Initializes a new instance of the <see cref="T:System.ServiceModel.Syndication.SyndicationTextInput" /> class.</summary>
4068
</Docs>
4169
</Member>
4270
<Member MemberName="Description">
@@ -57,9 +85,16 @@
5785
<ReturnType>System.String</ReturnType>
5886
</ReturnValue>
5987
<Docs>
60-
<summary>To be added.</summary>
61-
<value>To be added.</value>
62-
<remarks>To be added.</remarks>
88+
<summary>Gets or sets the description of the <c>textInput</c> feed item.</summary>
89+
<value>The description of the <c>textInput</c> feed item.</value>
90+
<remarks>
91+
<format type="text/markdown"><![CDATA[
92+
93+
## Remarks
94+
Defines a description of the text input element.
95+
96+
]]></format>
97+
</remarks>
6398
</Docs>
6499
</Member>
65100
<Member MemberName="Link">
@@ -80,9 +115,16 @@
80115
<ReturnType>System.ServiceModel.Syndication.SyndicationLink</ReturnType>
81116
</ReturnValue>
82117
<Docs>
83-
<summary>To be added.</summary>
84-
<value>To be added.</value>
85-
<remarks>To be added.</remarks>
118+
<summary>Gets or sets the url of the <c>textInput</c> feed item.</summary>
119+
<value>The url of the <c>textInput</c> feed item as a <see cref="T:System.ServiceModel.Syndication.SyndicationLink" />.</value>
120+
<remarks>
121+
<format type="text/markdown"><![CDATA[
122+
123+
## Remarks
124+
*Link* defines the URL endpoint which the input form will target.
125+
126+
]]></format>
127+
</remarks>
86128
</Docs>
87129
</Member>
88130
<Member MemberName="Name">
@@ -103,9 +145,16 @@
103145
<ReturnType>System.String</ReturnType>
104146
</ReturnValue>
105147
<Docs>
106-
<summary>To be added.</summary>
107-
<value>To be added.</value>
108-
<remarks>To be added.</remarks>
148+
<summary>Gets or sets the name of the <c>textInput</c> feed item.</summary>
149+
<value>The name of the <c>textInput</c> feed item.</value>
150+
<remarks>
151+
<format type="text/markdown"><![CDATA[
152+
153+
## Remarks
154+
Defines the name of the text input element to be shown.
155+
156+
]]></format>
157+
</remarks>
109158
</Docs>
110159
</Member>
111160
<Member MemberName="Title">
@@ -126,9 +175,16 @@
126175
<ReturnType>System.String</ReturnType>
127176
</ReturnValue>
128177
<Docs>
129-
<summary>To be added.</summary>
130-
<value>To be added.</value>
131-
<remarks>To be added.</remarks>
178+
<summary>Gets or sets the title of the <c>textInput</c> feed item.</summary>
179+
<value>The title of the <c>textInput</c> feed item.</value>
180+
<remarks>
181+
<format type="text/markdown"><![CDATA[
182+
183+
## Remarks
184+
*Title* defines the label of the submit button in the text input element.
185+
186+
]]></format>
187+
</remarks>
132188
</Docs>
133189
</Member>
134190
</Members>

‎xml/System.ServiceModel.Syndication/TryParseDateTimeCallback.xml

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,9 @@
2222
<ReturnType>System.Boolean</ReturnType>
2323
</ReturnValue>
2424
<Docs>
25-
<param name="data">To be added.</param>
26-
<param name="dateTimeOffset">To be added.</param>
27-
<summary>To be added.</summary>
28-
<returns>To be added.</returns>
29-
<remarks>To be added.</remarks>
25+
<param name="data">The raw date string contained in <see cref="T:System.ServiceModel.Syndication.XmlDateTimeData" /> to convert to a <see cref="T:System.DateTimeOffset" />.</param>
26+
<param name="dateTimeOffset">The resulting <see cref="T:System.DateTimeOffset" />.</param>
27+
<summary>A delegate type that is used by the <see cref="T:System.ServiceModel.Syndication.SyndicationFeedFormatter" /> class for converting <see cref="T:System.ServiceModel.Syndication.XmlDateTimeData" /> string data to <see cref="T:System.DateTimeOffset" />.</summary>
28+
<returns>A boolean value indicating whether or not the input string was successfully parsed.</returns>
3029
</Docs>
3130
</Type>

‎xml/System.ServiceModel.Syndication/TryParseUriCallback.xml

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,9 @@
2222
<ReturnType>System.Boolean</ReturnType>
2323
</ReturnValue>
2424
<Docs>
25-
<param name="data">To be added.</param>
26-
<param name="uri">To be added.</param>
27-
<summary>To be added.</summary>
28-
<returns>To be added.</returns>
29-
<remarks>To be added.</remarks>
25+
<param name="data">The raw string input to parse into a <see cref="T:System.Uri" /> object.</param>
26+
<param name="uri">The resulting <see cref="T:System.Uri" /> representation of the input string.</param>
27+
<summary>A delegate type that is used by the <see cref="T:System.ServiceModel.Syndication.SyndicationFeedFormatter" /> class for creating <see cref="T:System.Uri" /> instances from string input.</summary>
28+
<returns>A boolean value indicating whether or not the input string was successfully parsed.</returns>
3029
</Docs>
3130
</Type>

0 commit comments

Comments
 (0)