Add documentation to ALPN functionality in dart:io

sdk/lib/io/secure_socket.dart

Index: sdk/lib/io/secure_socket.dart
diff --git a/sdk/lib/io/secure_socket.dart b/sdk/lib/io/secure_socket.dart
index 630da499c4b37ef1c5dd1ed05e6cf5576b6088d2..77618efa79375edc4e13566d7ad338dc5b184a20 100644
--- a/sdk/lib/io/secure_socket.dart
+++ b/sdk/lib/io/secure_socket.dart
@@ -28,6 +28,11 @@ abstract class SecureSocket implements Socket {
    * decide (or let the user decide) whether to accept
    * the connection or not.  The handler should return true
    * to continue the [SecureSocket] connection.
+   *
+   * [supportedProtocols] is an optional list of protocols (in decreasing
+   * order of preference) to use during the ALPN protocol negogiation with the
+   * server.  Example values are "http/1.1" or "h2".  The selected protocol
+   * can be obtained via [SecureSocket.selectedProtocol].
    */
   static Future<SecureSocket> connect(host, int port,
       {SecurityContext context,
@@ -129,7 +134,11 @@ abstract class SecureSocket implements Socket {
   X509Certificate get peerCertificate;
 
   /**
-   * Get the protocol which was selected during protocol negotiation.
+   * Gets the protocol which was selected during ALPN protocol negotiation.

[floitsch, 2017/03/24 14:03:26]

The protocol ...
(drop the "Gets")

[kustermann, 2017/03/25 11:38:32]

Done.

+   *
+   * If one of the peers does not have support for ALPN, did not specify a

[floitsch, 2017/03/24 14:03:26]

Returns null if ...

Or
Is set to null if ...

[kustermann, 2017/03/25 11:38:32]

Done.

+   * list of supported ALPN protocols or there was no common protocol between
+   * client and server then this will return null.

[floitsch, 2017/03/24 14:03:26]

If you don't want to reshuffle the whole sentence, then "then this returns
null".
That said, we try to use "this" in dartdoc to imply "this instance".

[kustermann, 2017/03/25 11:38:32]

Reshuffled the sentence.

    */
   String get selectedProtocol;
 
@@ -174,6 +183,11 @@ abstract class RawSecureSocket implements RawSocket {
    * decide (or let the user decide) whether to accept
    * the connection or not.  The handler should return true
    * to continue the [RawSecureSocket] connection.
+   *
+   * [supportedProtocols] is an optional list of protocols (in decreasing
+   * order of preference) to use during the ALPN protocol negogiation with the
+   * server.  Example values are "http/1.1" or "h2".  The selected protocol
+   * can be obtained via [RawSecureSocket.selectedProtocol].
    */
   static Future<RawSecureSocket> connect(host, int port,
       {SecurityContext context,
@@ -300,7 +314,11 @@ abstract class RawSecureSocket implements RawSocket {
   X509Certificate get peerCertificate;
 
   /**
-   * Get the protocol which was selected during protocol negotiation.
+   * Gets the protocol which was selected during protocol negotiation.

[floitsch, 2017/03/24 14:03:26]

Same as above.

[kustermann, 2017/03/25 11:38:32]

Done.

+   *
+   * If one of the peers does not have support for ALPN, did not specify a
+   * list of supported ALPN protocols or there was no common protocol between
+   * client and server then this will return null.
    */
   String get selectedProtocol;
 }