[QUIC] Options classes fixes (#10828)

* Listener options fixes * Windows sizes power of 2 constraint * Small fixes * Removed non-existing namespace * Added links to conceptual docs * RFC link * callback details in summary * Links to conceptual docs for options classes * Update xml/System.Net.Quic/QuicClientConnectionOptions.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Net.Quic/QuicConnection.xml Co-authored-by: Genevieve Warren <[email protected]> * Update xml/System.Net.Quic/QuicConnectionOptions.xml Co-authored-by: Genevieve Warren <[email protected]> * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> --------- Co-authored-by: Genevieve Warren <[email protected]>
dotnet · Jan 22, 2025 · b1dc5b4 · b1dc5b4
1 parent 601c540
commit b1dc5b4
Show file tree

Hide file tree

Showing 10 changed files with 29 additions and 25 deletions.
diff --git a/xml/System.Net.Quic/QuicClientConnectionOptions.xml b/xml/System.Net.Quic/QuicClientConnectionOptions.xml
@@ -24,6 +24,7 @@
   <Docs>
     <summary>Options for client (outbound) <see cref="T:System.Net.Quic.QuicConnection">Quic connections</see>.</summary>
     <remarks>To be added.</remarks>
+    <related type="Article" href="/dotnet/fundamentals/networking/quic/quic-options#quicclientconnectionoptions">Detailed documentation for QuicClientConnectionOptions</related>
   </Docs>
   <Members>
     <Member MemberName=".ctor">

diff --git a/xml/System.Net.Quic/QuicConnection.xml b/xml/System.Net.Quic/QuicConnection.xml
@@ -41,6 +41,7 @@ For QUIC prerequisites and supported operating systems, see [Platform dependenci
       ]]></format>
     </remarks>
     <related type="Article" href="https://www.rfc-editor.org/rfc/rfc9000.html#name-connections">RFC 9000: Connections</related>
+    <related type="Article" href="/dotnet/fundamentals/networking/quic/quic-overview#quicconnection">Guidelines for using QuicConnection</related>
   </Docs>
   <Members>
     <Member MemberName="AcceptInboundStreamAsync">

diff --git a/xml/System.Net.Quic/QuicConnectionOptions.xml b/xml/System.Net.Quic/QuicConnectionOptions.xml
@@ -24,6 +24,7 @@
   <Docs>
     <summary>Shared options for both client (outbound) and server (inbound) <see cref="T:System.Net.Quic.QuicConnection">Quic connections</see>.</summary>
     <remarks>To be added.</remarks>
+    <related type="Article" href="/dotnet/fundamentals/networking/quic/quic-options#quicconnectionoptions">Detailed documentation for QuicConnectionOptions</related>
   </Docs>
   <Members>
     <Member MemberName="DefaultCloseErrorCode">
@@ -164,8 +165,8 @@ To use a different close error code, call <xref:System.Net.Quic.QuicConnection.C
         <ReturnType>System.TimeSpan</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets or sets the interval at which keep-alive packets are sent on the connection.</summary>
-        <value>The interval at which keep-alive packets are sent on the connection. The default value is <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" />, which means keep-alive packets are never sent.</value>
+        <summary>Gets or sets the interval at which PING frames are sent on the connection.</summary>
+        <value>The interval at which PING frames are sent on the connection. The default value is <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" />, which means PING frames are never sent.</value>
         <remarks>A value of <see cref="F:System.TimeSpan.Zero" /> means use the underlying implementation default timeout.</remarks>
       </Docs>
     </Member>
@@ -239,11 +240,12 @@ To use a different close error code, call <xref:System.Net.Quic.QuicConnection.C
       <Docs>
         <summary>
           <para>Optional callback that is invoked when new stream limit is released by the peer. Corresponds to receiving a MAX_STREAMS frame.</para>
-          <para>The callback values represent increments of stream limits, e.g.: current limit is 10 bidirectional streams, callback arguments notify 5 more additional bidirectional streams =&gt; 15 bidirectional streams can be opened in total at the moment.</para>
-          <para>The initial capacity is reported with the first invocation of the callback that might happen before the <see cref="T:System.Net.Quic.QuicConnection" /> instance is handed out via either <see cref="M:System.Net.Quic.QuicConnection.ConnectAsync(System.Net.Quic.QuicClientConnectionOptions,System.Threading.CancellationToken)" /> or <see cref="M:System.Net.Quic.QuicListener.AcceptConnectionAsync(System.Threading.CancellationToken)" />.</para>
         </summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <para>The callback values represent increments of stream limits. For example, if the current limit is 10 bidirectional streams, and callback arguments notify 5 more additional bidirectional streams, then 15 bidirectional streams can be opened in total at the moment.</para>
+          <para>The initial capacity is reported with the first invocation of the callback, which might happen before the <see cref="T:System.Net.Quic.QuicConnection" /> instance is handed out via either <see cref="M:System.Net.Quic.QuicConnection.ConnectAsync(System.Net.Quic.QuicClientConnectionOptions,System.Threading.CancellationToken)" /> or <see cref="M:System.Net.Quic.QuicListener.AcceptConnectionAsync(System.Threading.CancellationToken)" />.</para>
+        </remarks>
       </Docs>
     </Member>
   </Members>

diff --git a/xml/System.Net.Quic/QuicListener.xml b/xml/System.Net.Quic/QuicListener.xml
@@ -39,6 +39,7 @@ For QUIC prerequisites and supported operating systems, see [Platform dependenci
       ]]></format>
     </remarks>
     <related type="Article" href="https://www.rfc-editor.org/rfc/rfc9000.html#name-connections">RFC 9000: Connections</related>
+    <related type="Article" href="/dotnet/fundamentals/networking/quic/quic-overview#quiclistener">Guidelines for using QuicListener</related>
   </Docs>
   <Members>
     <Member MemberName="AcceptConnectionAsync">
@@ -69,9 +70,10 @@ For QUIC prerequisites and supported operating systems, see [Platform dependenci
 
 ## Remarks
 
-<xref:System.Net.Quic.QuicListener> doesn't have a mechanism to report inbound connections that fail the handshake process. Such connections are only logged by the listener and never surfaced on the outside.
-
-This method propagates exceptions from <xref:System.Net.Quic.QuicListenerOptions.ConnectionOptionsCallback>, including validation errors from misconfigured <xref:System.Net.Quic.QuicServerConnectionOptions>, for example, <xref:System.ArgumentException>. It also propagates exceptions from failed connection handshakes, for example, <xref:System.Security.Authentication.AuthenticationException> and <xref:System.Net.Quic.QuicException>.
+This method also propagates exceptions from the process of establishing a connection, including:
+- Errors from <xref:System.Net.Quic.QuicListenerOptions.ConnectionOptionsCallback> as <xref:System.Net.Quic.QuicException> with <xref:System.Net.Quic.QuicError.CallbackError> error type.
+- Validation errors from misconfigured <xref:System.Net.Quic.QuicServerConnectionOptions> returned by <xref:System.Net.Quic.QuicListenerOptions.ConnectionOptionsCallback> as <xref:System.ArgumentException>.
+- Exceptions from failed connection handshakes as <xref:System.Security.Authentication.AuthenticationException> or <xref:System.Net.Quic.QuicException>.
 
           ]]></format>
         </remarks>

diff --git a/xml/System.Net.Quic/QuicListenerOptions.xml b/xml/System.Net.Quic/QuicListenerOptions.xml
@@ -22,8 +22,9 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>Options to provide to a <see cref="T:System.Net.Quic.QuicListener" />.</summary>
+    <summary>Options to configure a new <see cref="T:System.Net.Quic.QuicListener" />.</summary>
     <remarks>To be added.</remarks>
+    <related type="Article" href="/dotnet/fundamentals/networking/quic/quic-options#quiclisteneroptions">Detailed documentation for QuicListenerOptions</related>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -65,7 +66,7 @@
       <Docs>
         <summary>Gets or sets the list of application protocols that the listener will accept. At least one must be specified.</summary>
         <value>To be added.</value>
-        <remarks>This property is mandatory, and not setting it will result in validation errors when starting the listener.</remarks>
+        <remarks>This property is mandatory. Not setting it or not specifying at least one value will result in validation errors when starting the listener.</remarks>
       </Docs>
     </Member>
     <Member MemberName="ConnectionOptionsCallback">
@@ -92,9 +93,9 @@
         <ReturnType>System.Func&lt;System.Net.Quic.QuicConnection,System.Net.Security.SslClientHelloInfo,System.Threading.CancellationToken,System.Threading.Tasks.ValueTask&lt;System.Net.Quic.QuicServerConnectionOptions&gt;&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets or sets the selection callback to choose inbound connection options dynamically.</summary>
+        <summary>Gets or sets the selection callback to choose inbound connection options.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>This property is mandatory. Not setting it will result in validation errors when starting the listener.</remarks>
       </Docs>
     </Member>
     <Member MemberName="ListenBacklog">
@@ -115,7 +116,7 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets or sets the number of connections to be held without accepting any of them, that is, the maximum size of the pending connection queue.</summary>
+        <summary>Gets or sets the number of connections to be held without accepting any of them. That is, the maximum size of the pending connection queue.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -140,7 +141,7 @@
       <Docs>
         <summary>Gets or sets the endpoint to listen on.</summary>
         <value>To be added.</value>
-        <remarks>This property is mandatory, and not setting it will result in validation errors when starting the listener.</remarks>
+        <remarks>This property is mandatory. Not setting it will result in validation errors when starting the listener.</remarks>
       </Docs>
     </Member>
   </Members>

diff --git a/xml/System.Net.Quic/QuicReceiveWindowSizes.xml b/xml/System.Net.Quic/QuicReceiveWindowSizes.xml
@@ -53,7 +53,7 @@
       <Docs>
         <summary>Gets or sets the initial flow-control window size for the connection.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>Must be non-negative power of 2.</remarks>
       </Docs>
     </Member>
     <Member MemberName="LocallyInitiatedBidirectionalStream">
@@ -74,7 +74,7 @@
       <Docs>
         <summary>Gets or sets the initial flow-control window size for locally initiated bidirectional streams.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>Must be non-negative power of 2.</remarks>
       </Docs>
     </Member>
     <Member MemberName="RemotelyInitiatedBidirectionalStream">
@@ -95,7 +95,7 @@
       <Docs>
         <summary>Gets or sets the initial flow-control window size for remotely initiated bidirectional streams.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>Must be non-negative power of 2.</remarks>
       </Docs>
     </Member>
     <Member MemberName="UnidirectionalStream">
@@ -116,7 +116,7 @@
       <Docs>
         <summary>Gets or sets the initial flow-control window size for (remotely initiated) unidirectional streams.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>Must be non-negative power of 2.</remarks>
       </Docs>
     </Member>
   </Members>

diff --git a/xml/System.Net.Quic/QuicServerConnectionOptions.xml b/xml/System.Net.Quic/QuicServerConnectionOptions.xml
@@ -24,6 +24,7 @@
   <Docs>
     <summary>Options for server (inbound) <see cref="T:System.Net.Quic.QuicConnection">Quic connections</see>. These options are provided by <see cref="P:System.Net.Quic.QuicListenerOptions.ConnectionOptionsCallback" />.</summary>
     <remarks>To be added.</remarks>
+    <related type="Article" href="/dotnet/fundamentals/networking/quic/quic-options#quicserverconnectionoptions">Detailed documentation for QuicServerConnectionOptions</related>
   </Docs>
   <Members>
     <Member MemberName=".ctor">

diff --git a/xml/System.Net.Quic/QuicStream.xml b/xml/System.Net.Quic/QuicStream.xml
@@ -30,6 +30,7 @@ Apart from a stream API, <see cref="T:System.Net.Quic.QuicStream" /> also expose
 
 <list type="bullet"><item><term><see cref="M:System.Net.Quic.QuicStream.WriteAsync(System.ReadOnlyMemory{System.Byte},System.Boolean,System.Threading.CancellationToken)" /></term><description>Closes the writing side of the stream as a single operation with the write itself.</description></item><item><term><see cref="M:System.Net.Quic.QuicStream.CompleteWrites" /></term><description>Closes the writing side of the stream.</description></item><item><term><see cref="M:System.Net.Quic.QuicStream.Abort(System.Net.Quic.QuicAbortDirection,System.Int64)" /></term><description>Aborts either the writing or the reading side of the stream.</description></item><item><term><see cref="M:System.Net.Quic.QuicStream.WritesClosed" /></term><description>Returns a <see cref="T:System.Threading.Tasks.Task" /> that will complete when the stream writing side has been closed (gracefully or abortively).</description></item><item><term><see cref="P:System.Net.Quic.QuicStream.ReadsClosed" /></term><description>Returns a <see cref="T:System.Threading.Tasks.Task" /> that will complete when the stream reading side has been closed (gracefully or abortively).</description></item></list></remarks>
     <related type="Article" href="https://www.rfc-editor.org/rfc/rfc9000.html#name-streams">RFC 9000: Streams</related>
+    <related type="Article" href="/dotnet/fundamentals/networking/quic/quic-overview#quicstream">Guidelines for using QuicStream</related>
   </Docs>
   <Members>
     <Member MemberName="Abort">

diff --git a/xml/ns-System.Net.Quic.Implementations.xml b/xml/ns-System.Net.Quic.Implementations.xml
diff --git a/xml/ns-System.Net.Quic.xml b/xml/ns-System.Net.Quic.xml
@@ -1,6 +1,7 @@
 <Namespace Name="System.Net.Quic">
   <Docs>
-    <summary>Contains types that implement the QUIC protocol specified by RFC 9000.</summary>
+    <summary>Contains types that implement the QUIC protocol specified by <see href="https://www.rfc-editor.org/rfc/rfc9000.html">RFC 9000</see>.</summary>
     <remarks>To be added.</remarks>
+    <related type="Article" href="/dotnet/fundamentals/networking/quic/quic-overview">QUIC in .NET</related>
   </Docs>
 </Namespace>