From 5236f8c9e20dc82e5b072a16b034de05d720e500 Mon Sep 17 00:00:00 2001
From: Jon Parise <jon@php.net>
Date: Fri, 19 Mar 2021 09:21:18 -0700
Subject: [PATCH] Document the new starttls() method

---
 Net/SMTP.php | 3 ++-
 README.rst   | 6 ++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/Net/SMTP.php b/Net/SMTP.php
index 69e84f9..7ee170d 100644
--- a/Net/SMTP.php
+++ b/Net/SMTP.php
@@ -573,7 +573,8 @@ protected function getBestAuthMethod()
      * Establish STARTTLS Connection.
      *
      * @return mixed Returns a PEAR_Error with an error message on any
-     *               kind of failure, or true on success.
+     *               kind of failure, true on success, or false if SSL/TLS
+     *               isn't available.
      * @since 1.9.3
      */
     public function starttls()
diff --git a/README.rst b/README.rst
index e2428f5..3871fb9 100644
--- a/README.rst
+++ b/README.rst
@@ -141,7 +141,13 @@ establish a secure connection to the remote SMTP server::
 This example connects to ``mail.example.com`` on port 465 (a common SMTPS
 port) using the ``ssl://`` transport.
 
+TLS/SSL is enabled for authenticated connections by default (via the ``auth()``
+method's ``$tls`` parameter), but the |STARTTLS|_ command can also be sent
+manually using the ``starttls()`` method.
+
 .. _secure socket transports: https://www.php.net/transports
+.. |STARTTLS| replace:: ``STARTTLS``
+.. _STARTTLS: https://tools.ietf.org/html/rfc3207
 
 Sending Data
 ============