From 6fadd68da5dd928847264b17f62a5b8b369c1c1e Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend@python.org>
Date: Wed, 24 Jan 2024 16:06:14 +0100
Subject: [PATCH] Docs: mark up the FTP_TLS() docs with param list (#114510)

Also turn sentence about prot_p() into a note.
---
 Doc/library/ftplib.rst | 56 ++++++++++++++++++++++++++++++++++--------
 1 file changed, 46 insertions(+), 10 deletions(-)

diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index e93a1e85598..2f98a272c29 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -78,6 +78,9 @@ FTP objects
    A 2-tuple ``(host, port)`` for the socket to bind to as its
    source address before connecting.
 
+.. |param_doc_encoding| replace::
+   The encoding for directories and filenames (default: ``'utf-8'``).
+
 .. class:: FTP(host='', user='', passwd='', acct='', timeout=None, \
                source_address=None, *, encoding='utf-8')
 
@@ -108,8 +111,7 @@ FTP objects
    :type source_address: tuple | None
 
    :param str encoding:
-      The *encoding* parameter specifies the encoding
-      for directories and filenames.
+      |param_doc_encoding|
 
    The :class:`FTP` class supports the :keyword:`with` statement, e.g.:
 
@@ -447,19 +449,53 @@ FTP_TLS objects
 .. class:: FTP_TLS(host='', user='', passwd='', acct='', *, context=None, \
                    timeout=None, source_address=None, encoding='utf-8')
 
-   A :class:`FTP` subclass which adds TLS support to FTP as described in
+   An :class:`FTP` subclass which adds TLS support to FTP as described in
    :rfc:`4217`.
-   Connect as usual to port 21 implicitly securing the FTP control connection
-   before authenticating. Securing the data connection requires the user to
-   explicitly ask for it by calling the :meth:`prot_p` method.  *context*
-   is a :class:`ssl.SSLContext` object which allows bundling SSL configuration
-   options, certificates and private keys into a single (potentially
-   long-lived) structure.  Please read :ref:`ssl-security` for best practices.
+   Connect to port 21 implicitly securing the FTP control connection
+   before authenticating.
+
+   .. note::
+      The user must explicitly secure the data connection
+      by calling the :meth:`prot_p` method.
+
+   :param str host:
+      The hostname to connect to.
+      If given, :code:`connect(host)` is implicitly called by the constructor.
+
+   :param str user:
+      |param_doc_user|
+      If given, :code:`login(host, passwd, acct)` is implicitly called
+      by the constructor.
+
+   :param str passwd:
+      |param_doc_passwd|
+
+   :param str acct:
+      |param_doc_acct|
+
+   :param context:
+      An SSL context object which allows bundling SSL configuration options,
+      certificates and private keys into a single, potentially long-lived,
+      structure.
+      Please read :ref:`ssl-security` for best practices.
+   :type context: :class:`ssl.SSLContext`
+
+   :param timeout:
+      A timeout in seconds for blocking operations like :meth:`~FTP.connect`
+      (default: the global default timeout setting).
+   :type timeout: int | None
+
+   :param source_address:
+      |param_doc_source_address|
+   :type source_address: tuple | None
+
+   :param str encoding:
+      |param_doc_encoding|
 
    .. versionadded:: 3.2
 
    .. versionchanged:: 3.3
-      *source_address* parameter was added.
+      Added the *source_address* parameter.
 
    .. versionchanged:: 3.4
       The class now supports hostname check with