dart:io | Add documentation for the default root certificate database for secure networking.

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 08912cc8c199858274ba26d53904a25aa9012e48..5bb3aba8eaa092ece7f49f89ea65988e671d7e7e 100644
--- a/sdk/lib/io/secure_socket.dart
+++ b/sdk/lib/io/secure_socket.dart
@@ -149,23 +149,28 @@ abstract class SecureSocket implements Socket {
    * arguments.
    *
    * The optional argument [database] is the path to a certificate database
-   * containing root certificates for verifying certificate paths on
+   * directory containing root certificates for verifying certificate paths on
    * client connections, and server certificates to provide on server
    * connections.  The argument [password] should be used when creating
    * secure server sockets, to allow the private key of the server
    * certificate to be fetched.  If [useBuiltinRoots] is true (the default),
    * then a built-in set of root certificates for trusted certificate
    * authorities is merged with the certificates in the database.
+   * The list of built-in root certificates, and documentation about this
+   * default database, is available at
+   * http://www.mozilla.org/projects/security/certs/included/ .
+   * If no value is provided for the [database] argument, then only the

[Lasse Reichstein Nielsen, 2013/05/31 08:49:06]

We'd usually write "If the [database] argument is omitted, then ...".

[Bill Hesse, 2013/05/31 09:08:38]

Done.

+   * builtin root certificates are used, unless they are disabled.

[Lasse Reichstein Nielsen, 2013/05/31 08:49:06]

"unless they are disabled"?
How can they be disabled? What happens if they are?
The "unless" could be seen as being relative to the "only", so if the root
certificates are disabled, more than just the root certificates are used.

How about.
"... onlt the builtin root certificates are used. If they are also disabled,
...<something happens - no certificates are used?>"

[Bill Hesse, 2013/05/31 09:08:38]

Done.

    *
    * Examples:
    *   1) Use only the builtin root certificates:
    *     SecureSocket.initialize(); or
    *
-   *   2) Use a specified database and the builtin roots:
+   *   2) Use a specified database directory and the builtin roots:
    *     SecureSocket.initialize(database: 'path/to/my/database',
    *                             password: 'my_password');
    *
-   *   3) Use a specified database, without builtin roots:
+   *   3) Use a specified database directory, without builtin roots:
    *     SecureSocket.initialize(database: 'path/to/my/database',
    *                             password: 'my_password'.
    *                             useBuiltinRoots: false);

[Lasse Reichstein Nielsen, 2013/05/31 08:49:06]

So what happens if you do:
  initialize(password: "my_password", useBuiltinRoots: false)
?

[Bill Hesse, 2013/05/31 09:08:38]

Nothing useful.  No certificates are available.  you can't do much.