[Python-checkins] smtplib documentation fixes (GH-8708)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/6c140609770ba161a5bb8aa36ecef0d38e6642df
commit: 6c140609770ba161a5bb8aa36ecef0d38e6642df
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2018-08-12T21:06:22-07:00
summary:

smtplib documentation fixes (GH-8708)


* SMTP.startssl: Fix doc on keyfile and certfile use

* SMTP.startssl: Add missing keyfile and certfile deprecation notice

* SMTP: Doc grammar fixes
(cherry picked from commit da12063f2f53b7d272824863ed24260cefb22e8c)

Co-authored-by: Ville Skyttä <ville.skytta at iki.fi>

files:
M Doc/library/smtplib.rst

diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index 86e769e6a1f8..e5effd0306a4 100644
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -271,7 +271,7 @@ An :class:`SMTP` instance has the following methods:
 
 .. method:: SMTP.ehlo_or_helo_if_needed()
 
-   This method call :meth:`ehlo` and or :meth:`helo` if there has been no
+   This method calls :meth:`ehlo` and/or :meth:`helo` if there has been no
    previous ``EHLO`` or ``HELO`` command this session.  It tries ESMTP ``EHLO``
    first.
 
@@ -379,16 +379,23 @@ An :class:`SMTP` instance has the following methods:
    commands that follow will be encrypted.  You should then call :meth:`ehlo`
    again.
 
-   If *keyfile* and *certfile* are provided, these are passed to the :mod:`socket`
-   module's :func:`ssl` function.
+   If *keyfile* and *certfile* are provided, they are used to create an
+   :class:`ssl.SSLContext`.
 
-   Optional *context* parameter is a :class:`ssl.SSLContext` object; This is
+   Optional *context* parameter is an :class:`ssl.SSLContext` object; This is
    an alternative to using a keyfile and a certfile and if specified both
    *keyfile* and *certfile* should be ``None``.
 
    If there has been no previous ``EHLO`` or ``HELO`` command this session,
    this method tries ESMTP ``EHLO`` first.
 
+   .. deprecated:: 3.6
+
+       *keyfile* and *certfile* are deprecated in favor of *context*.
+       Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
+       :func:`ssl.create_default_context` select the system's trusted CA
+       certificates for you.
+
    :exc:`SMTPHeloError`
       The server didn't reply properly to the ``HELO`` greeting.