Issue #18761: Improved cross-references in email documentation.

10 files changed, 208 insertions, 156 deletions

diff --git a/Doc/library/email.charset.rst b/Doc/library/email.charset.rst
index a828f3c..19a6953 100644
--- a/Doc/library/email.charset.rst
+++ b/Doc/library/email.charset.rst
@@ -234,5 +234,5 @@ new entries to the global character set, alias, and codec registries:
 
    *charset* is the canonical name of a character set. *codecname* is the name of a
    Python codec, as appropriate for the second argument to the :class:`str`'s
-   :func:`decode` method
+   :meth:`~str.encode` method
 
diff --git a/Doc/library/email.errors.rst b/Doc/library/email.errors.rst
index 9f0a9e2..294e3ed 100644
--- a/Doc/library/email.errors.rst
+++ b/Doc/library/email.errors.rst
@@ -25,7 +25,8 @@ The following exception classes are defined in the :mod:`email.errors` module:
 
    Raised under some error conditions when parsing the :rfc:`2822` headers of a
    message, this class is derived from :exc:`MessageParseError`. It can be raised
-   from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
+   from the :meth:`Parser.parse <email.parser.Parser.parse>` or
+   :meth:`Parser.parsestr <email.parser.Parser.parsestr>` methods.
 
    Situations where it can be raised include finding an envelope header after the
    first :rfc:`2822` header of the message, finding a continuation line before the
@@ -37,7 +38,8 @@ The following exception classes are defined in the :mod:`email.errors` module:
 
    Raised under some error conditions when parsing the :rfc:`2822` headers of a
    message, this class is derived from :exc:`MessageParseError`. It can be raised
-   from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
+   from the :meth:`Parser.parse <email.parser.Parser.parse>` or
+   :meth:`Parser.parsestr <email.parser.Parser.parsestr>` methods.
 
    Situations where it can be raised include not being able to find the starting or
    terminating boundary in a :mimetype:`multipart/\*` message when strict parsing
@@ -46,19 +48,20 @@ The following exception classes are defined in the :mod:`email.errors` module:
 
 .. exception:: MultipartConversionError()
 
-   Raised when a payload is added to a :class:`Message` object using
-   :meth:`add_payload`, but the payload is already a scalar and the message's
-   :mailheader:`Content-Type` main type is not either :mimetype:`multipart` or
-   missing.  :exc:`MultipartConversionError` multiply inherits from
-   :exc:`MessageError` and the built-in :exc:`TypeError`.
+   Raised when a payload is added to a :class:`~email.message.Message` object
+   using :meth:`add_payload`, but the payload is already a scalar and the
+   message's :mailheader:`Content-Type` main type is not either
+   :mimetype:`multipart` or missing.  :exc:`MultipartConversionError` multiply
+   inherits from :exc:`MessageError` and the built-in :exc:`TypeError`.
 
-   Since :meth:`Message.add_payload` is deprecated, this exception is rarely raised
-   in practice.  However the exception may also be raised if the :meth:`attach`
+   Since :meth:`Message.add_payload` is deprecated, this exception is rarely
+   raised in practice.  However the exception may also be raised if the
+   :meth:`~email.message.Message.attach`
    method is called on an instance of a class derived from
    :class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
    :class:`~email.mime.image.MIMEImage`).
 
-Here's the list of the defects that the :class:`~email.mime.parser.FeedParser`
+Here's the list of the defects that the :class:`~email.parser.FeedParser`
 can find while parsing messages.  Note that the defects are added to the message
 where the problem was found, so for example, if a message nested inside a
 :mimetype:`multipart/alternative` had a malformed header, that nested message
@@ -97,9 +100,9 @@ this class is *not* an exception!
      This defect has not been used for several Python versions.
 
 * :class:`MultipartInvariantViolationDefect` -- A message claimed to be a
-  :mimetype:`multipart`, but no subparts were found.  Note that when a message has
-  this defect, its :meth:`is_multipart` method may return false even though its
-  content type claims to be :mimetype:`multipart`.
+  :mimetype:`multipart`, but no subparts were found.  Note that when a message
+  has this defect, its :meth:`~email.message.Message.is_multipart` method may
+  return false even though its content type claims to be :mimetype:`multipart`.
 
 * :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64
   enocded bytes, the padding was not correct.  Enough padding is added to
diff --git a/Doc/library/email.headerregistry.rst b/Doc/library/email.headerregistry.rst
index c884159..db3aade 100644
--- a/Doc/library/email.headerregistry.rst
+++ b/Doc/library/email.headerregistry.rst
@@ -56,15 +56,16 @@ headers.
    .. attribute:: name
 
       The name of the header (the portion of the field before the ':').  This
-      is exactly the value passed in the :attr:`~EmailPolicy.header_factory`
-      call for *name*; that is, case is preserved.
+      is exactly the value passed in the
+      :attr:`~email.policy.EmailPolicy.header_factory` call for *name*; that
+      is, case is preserved.
 
 
    .. attribute:: defects
 
       A tuple of :exc:`~email.errors.HeaderDefect` instances reporting any
       RFC compliance problems found during parsing.  The email package tries to
-      be complete about detecting compliance issues.  See the :mod:`errors`
+      be complete about detecting compliance issues.  See the :mod:`~email.errors`
       module for a discussion of the types of defects that may be reported.
 
 
@@ -230,8 +231,8 @@ headers.
 
       The single address encoded by the header value.  If the header value
       actually contains more than one address (which would be a violation of
-      the RFC under the default :mod:`policy`), accessing this attribute will
-      result in a :exc:`ValueError`.
+      the RFC under the default :mod:`~email.policy`), accessing this attribute
+      will result in a :exc:`ValueError`.
 
 
 Many of the above classes also have a ``Unique`` variant (for example,
@@ -275,7 +276,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
 
 .. class:: ContentTypeHeader
 
-    A :class:`ParameterizedMIMEHheader` class that handles the
+    A :class:`ParameterizedMIMEHeader` class that handles the
     :mailheader:`Content-Type` header.
 
     .. attribute:: content_type
@@ -289,7 +290,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
 
 .. class:: ContentDispositionHeader
 
-    A :class:`ParameterizedMIMEHheader` class that handles the
+    A :class:`ParameterizedMIMEHeader` class that handles the
     :mailheader:`Content-Disposition` header.
 
     .. attribute:: content-disposition
diff --git a/Doc/library/email.iterators.rst b/Doc/library/email.iterators.rst
index 7882718..f92f460 100644
--- a/Doc/library/email.iterators.rst
+++ b/Doc/library/email.iterators.rst
@@ -6,8 +6,9 @@
 
 
 Iterating over a message object tree is fairly easy with the
-:meth:`Message.walk` method.  The :mod:`email.iterators` module provides some
-useful higher level iterations over message object trees.
+:meth:`Message.walk <email.message.Message.walk>` method.  The
+:mod:`email.iterators` module provides some useful higher level iterations over
+message object trees.
 
 
 .. function:: body_line_iterator(msg, decode=False)
@@ -16,9 +17,11 @@ useful higher level iterations over message object trees.
    string payloads line-by-line.  It skips over all the subpart headers, and it
    skips over any subpart with a payload that isn't a Python string.  This is
    somewhat equivalent to reading the flat text representation of the message from
-   a file using :meth:`readline`, skipping over all the intervening headers.
+   a file using :meth:`~io.TextIOBase.readline`, skipping over all the
+   intervening headers.
 
-   Optional *decode* is passed through to :meth:`Message.get_payload`.
+   Optional *decode* is passed through to :meth:`Message.get_payload
+   <email.message.Message.get_payload>`.
 
 
 .. function:: typed_subpart_iterator(msg, maintype='text', subtype=None)
diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
index 2d07a0a..576531d 100644
--- a/Doc/library/email.message.rst
+++ b/Doc/library/email.message.rst
@@ -55,8 +55,8 @@ Here are the methods of the :class:`Message` class:
       format the message the way you want.  For example, by default it does
       not do the mangling of lines that begin with ``From`` that is
       required by the unix mbox format.  For more flexibility, instantiate a
-      :class:`~email.generator.Generator` instance and use its :meth:`flatten`
-      method directly.  For example::
+      :class:`~email.generator.Generator` instance and use its
+      :meth:`~email.generator.Generator.flatten` method directly.  For example::
 
          from io import StringIO
          from email.generator import Generator
@@ -476,8 +476,8 @@ Here are the methods of the :class:`Message` class:
 
       Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
       *boundary*.  :meth:`set_boundary` will always quote *boundary* if
-      necessary.  A :exc:`HeaderParseError` is raised if the message object has
-      no :mailheader:`Content-Type` header.
+      necessary.  A :exc:`~email.errors.HeaderParseError` is raised if the
+      message object has no :mailheader:`Content-Type` header.
 
       Note that using this method is subtly different than deleting the old
       :mailheader:`Content-Type` header and adding a new one with the new
@@ -573,7 +573,8 @@ Here are the methods of the :class:`Message` class:
       the end of the message.
 
       You do not need to set the epilogue to the empty string in order for the
-      :class:`Generator` to print a newline at the end of the file.
+      :class:`~email.generator.Generator` to print a newline at the end of the
+      file.
 
 
    .. attribute:: defects
diff --git a/Doc/library/email.mime.rst b/Doc/library/email.mime.rst
index 192e353..4cdb322 100644
--- a/Doc/library/email.mime.rst
+++ b/Doc/library/email.mime.rst
@@ -35,7 +35,8 @@ Here are the classes:
    *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
    or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
    type  (e.g. :mimetype:`plain` or :mimetype:`gif`).  *_params* is a parameter
-   key/value dictionary and is passed directly to :meth:`Message.add_header`.
+   key/value dictionary and is passed directly to :meth:`Message.add_header
+   <email.message.Message.add_header>`.
 
    The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
    (based on *_maintype*, *_subtype*, and *_params*), and a
@@ -50,8 +51,9 @@ Here are the classes:
 
    A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
    class for MIME messages that are not :mimetype:`multipart`.  The primary
-   purpose of this class is to prevent the use of the :meth:`attach` method,
-   which only makes sense for :mimetype:`multipart` messages.  If :meth:`attach`
+   purpose of this class is to prevent the use of the
+   :meth:`~email.message.Message.attach` method, which only makes sense for
+   :mimetype:`multipart` messages.  If :meth:`~email.message.Message.attach`
    is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
 
 
@@ -74,7 +76,8 @@ Here are the classes:
 
    *_subparts* is a sequence of initial subparts for the payload.  It must be
    possible to convert this sequence to a list.  You can always attach new subparts
-   to the message by using the :meth:`Message.attach` method.
+   to the message by using the :meth:`Message.attach
+   <email.message.Message.attach>` method.
 
    Additional parameters for the :mailheader:`Content-Type` header are taken from
    the keyword arguments, or passed into the *_params* argument, which is a keyword
@@ -95,8 +98,10 @@ Here are the classes:
 
    Optional *_encoder* is a callable (i.e. function) which will perform the actual
    encoding of the data for transport.  This callable takes one argument, which is
-   the :class:`MIMEApplication` instance. It should use :meth:`get_payload` and
-   :meth:`set_payload` to change the payload to encoded form.  It should also add
+   the :class:`MIMEApplication` instance. It should use
+   :meth:`~email.message.Message.get_payload` and
+   :meth:`~email.message.Message.set_payload` to change the payload to encoded
+   form.  It should also add
    any :mailheader:`Content-Transfer-Encoding` or other headers to the message
    object as necessary.  The default encoding is base64.  See the
    :mod:`email.encoders` module for a list of the built-in encoders.
@@ -121,8 +126,10 @@ Here are the classes:
 
    Optional *_encoder* is a callable (i.e. function) which will perform the actual
    encoding of the audio data for transport.  This callable takes one argument,
-   which is the :class:`MIMEAudio` instance. It should use :meth:`get_payload` and
-   :meth:`set_payload` to change the payload to encoded form.  It should also add
+   which is the :class:`MIMEAudio` instance. It should use
+   :meth:`~email.message.Message.get_payload` and
+   :meth:`~email.message.Message.set_payload` to change the payload to encoded
+   form.  It should also add
    any :mailheader:`Content-Transfer-Encoding` or other headers to the message
    object as necessary.  The default encoding is base64.  See the
    :mod:`email.encoders` module for a list of the built-in encoders.
@@ -147,8 +154,10 @@ Here are the classes:
 
    Optional *_encoder* is a callable (i.e. function) which will perform the actual
    encoding of the image data for transport.  This callable takes one argument,
-   which is the :class:`MIMEImage` instance. It should use :meth:`get_payload` and
-   :meth:`set_payload` to change the payload to encoded form.  It should also add
+   which is the :class:`MIMEImage` instance. It should use
+   :meth:`~email.message.Message.get_payload` and
+   :meth:`~email.message.Message.set_payload` to change the payload to encoded
+   form.  It should also add
    any :mailheader:`Content-Transfer-Encoding` or other headers to the message
    object as necessary.  The default encoding is base64.  See the
    :mod:`email.encoders` module for a list of the built-in encoders.
diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
index 6a43561..ee6af3f 100644
--- a/Doc/library/email.parser.rst
+++ b/Doc/library/email.parser.rst
@@ -7,7 +7,8 @@
 
 Message object structures can be created in one of two ways: they can be created
 from whole cloth by instantiating :class:`~email.message.Message` objects and
-stringing them together via :meth:`attach` and :meth:`set_payload` calls, or they
+stringing them together via :meth:`~email.message.Message.attach` and
+:meth:`~email.message.Message.set_payload` calls, or they
 can be created by parsing a flat text representation of the email message.
 
 The :mod:`email` package provides a standard parser that understands most email
@@ -16,8 +17,9 @@ or a file object, and the parser will return to you the root
 :class:`~email.message.Message` instance of the object structure.  For simple,
 non-MIME messages the payload of this root object will likely be a string
 containing the text of the message.  For MIME messages, the root object will
-return ``True`` from its :meth:`is_multipart` method, and the subparts can be
-accessed via the :meth:`get_payload` and :meth:`walk` methods.
+return ``True`` from its :meth:`~email.message.Message.is_multipart` method, and
+the subparts can be accessed via the :meth:`~email.message.Message.get_payload`
+and :meth:`~email.message.Message.walk` methods.
 
 There are actually two parser interfaces available for use, the classic
 :class:`Parser` API and the incremental :class:`FeedParser` API.  The classic
@@ -134,7 +136,8 @@ have the same API as the :class:`Parser` and :class:`BytesParser` classes.
 
       Read all the data from the file-like object *fp*, parse the resulting
       text, and return the root message object.  *fp* must support both the
-      :meth:`readline` and the :meth:`read` methods on file-like objects.
+      :meth:`~io.TextIOBase.readline` and the :meth:`~io.TextIOBase.read`
+      methods on file-like objects.
 
       The text contained in *fp* must be formatted as a block of :rfc:`2822`
       style headers and header continuation lines, optionally preceded by a
@@ -173,8 +176,8 @@ have the same API as the :class:`Parser` and :class:`BytesParser` classes.
 
       Read all the data from the binary file-like object *fp*, parse the
       resulting bytes, and return the message object.  *fp* must support
-      both the :meth:`readline` and the :meth:`read` methods on file-like
-      objects.
+      both the :meth:`~io.IOBase.readline` and the :meth:`~io.IOBase.read`
+      methods on file-like objects.
 
       The bytes contained in *fp* must be formatted as a block of :rfc:`2822`
       style headers and header continuation lines, optionally preceded by a
@@ -210,7 +213,7 @@ in the top-level :mod:`email` package namespace.
 
    Return a message object structure from a string.  This is exactly equivalent to
    ``Parser().parsestr(s)``.  *_class* and *policy* are interpreted as
-   with the :class:`Parser` class constructor.
+   with the :class:`~email.parser.Parser` class constructor.
 
    .. versionchanged:: 3.3
       Removed the *strict* argument.  Added the *policy* keyword.
@@ -220,7 +223,8 @@ in the top-level :mod:`email` package namespace.
 
    Return a message object structure from a byte string.  This is exactly
    equivalent to ``BytesParser().parsebytes(s)``.  Optional *_class* and
-   *strict* are interpreted as with the :class:`Parser` class constructor.
+   *strict* are interpreted as with the :class:`~email.parser.Parser` class
+   constructor.
 
    .. versionadded:: 3.2
    .. versionchanged:: 3.3
@@ -231,7 +235,8 @@ in the top-level :mod:`email` package namespace.
 
    Return a message object structure tree from an open :term:`file object`.
    This is exactly equivalent to ``Parser().parse(fp)``.  *_class*
-   and *policy* are interpreted as with the :class:`Parser` class constructor.
+   and *policy* are interpreted as with the :class:`~email.parser.Parser` class
+   constructor.
 
    .. versionchanged::
       Removed the *strict* argument.  Added the *policy* keyword.
@@ -241,8 +246,8 @@ in the top-level :mod:`email` package namespace.
 
    Return a message object structure tree from an open binary :term:`file
    object`.  This is exactly equivalent to ``BytesParser().parse(fp)``.
-   *_class* and *policy* are interpreted as with the :class:`Parser`
-   class constructor.
+   *_class* and *policy* are interpreted as with the
+   :class:`~email.parser.Parser` class constructor.
 
    .. versionadded:: 3.2
    .. versionchanged:: 3.3
@@ -261,32 +266,35 @@ Here are some notes on the parsing semantics:
 
 * Most non-\ :mimetype:`multipart` type messages are parsed as a single message
   object with a string payload.  These objects will return ``False`` for
-  :meth:`is_multipart`.  Their :meth:`get_payload` method will return a string
-  object.
+  :meth:`~email.message.Message.is_multipart`.  Their
+  :meth:`~email.message.Message.get_payload` method will return a string object.
 
 * All :mimetype:`multipart` type messages will be parsed as a container message
   object with a list of sub-message objects for their payload.  The outer
-  container message will return ``True`` for :meth:`is_multipart` and their
-  :meth:`get_payload` method will return the list of :class:`~email.message.Message`
-  subparts.
+  container message will return ``True`` for
+  :meth:`~email.message.Message.is_multipart` and their
+  :meth:`~email.message.Message.get_payload` method will return the list of
+  :class:`~email.message.Message` subparts.
 
 * Most messages with a content type of :mimetype:`message/\*` (e.g.
   :mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be
   parsed as container object containing a list payload of length 1.  Their
-  :meth:`is_multipart` method will return ``True``.  The single element in the
-  list payload will be a sub-message object.
+  :meth:`~email.message.Message.is_multipart` method will return ``True``.
+  The single element in the list payload will be a sub-message object.
 
 * Some non-standards compliant messages may not be internally consistent about
   their :mimetype:`multipart`\ -edness.  Such messages may have a
   :mailheader:`Content-Type` header of type :mimetype:`multipart`, but their
-  :meth:`is_multipart` method may return ``False``.  If such messages were parsed
-  with the :class:`FeedParser`, they will have an instance of the
-  :class:`MultipartInvariantViolationDefect` class in their *defects* attribute
-  list.  See :mod:`email.errors` for details.
+  :meth:`~email.message.Message.is_multipart` method may return ``False``.
+  If such messages were parsed with the :class:`~email.parser.FeedParser`,
+  they will have an instance of the
+  :class:`~email.errors.MultipartInvariantViolationDefect` class in their
+  *defects* attribute list.  See :mod:`email.errors` for details.
 
 .. rubric:: Footnotes
 
 .. [#] As of email package version 3.0, introduced in Python 2.4, the classic
-   :class:`Parser` was re-implemented in terms of the :class:`FeedParser`, so the
-   semantics and results are identical between the two parsers.
+   :class:`~email.parser.Parser` was re-implemented in terms of the
+   :class:`~email.parser.FeedParser`, so the semantics and results are
+   identical between the two parsers.
 
diff --git a/Doc/library/email.policy.rst b/Doc/library/email.policy.rst
index 99806ee..cb2023c 100644
--- a/Doc/library/email.policy.rst
+++ b/Doc/library/email.policy.rst
@@ -304,7 +304,7 @@ added matters.  To illustrate::
 
    This concrete :class:`Policy` is the backward compatibility policy.  It
    replicates the behavior of the email package in Python 3.2.  The
-   :mod:`policy` module also defines an instance of this class,
+   :mod:`~email.policy` module also defines an instance of this class,
    :const:`compat32`, that is used as the default policy.  Thus the default
    behavior of the email package is to maintain compatibility with Python 3.2.
 
@@ -448,10 +448,11 @@ added matters.  To illustrate::
 
    .. method:: fold_binary(name, value)
 
-      The same as :meth:`fold` if :attr:`cte_type` is ``7bit``, except that
-      the returned value is bytes.
+      The same as :meth:`fold` if :attr:`~Policy.cte_type` is ``7bit``, except
+      that the returned value is bytes.
 
-      If :attr:`cte_type` is ``8bit``, non-ASCII binary data is converted back
+      If :attr:`~Policy.cte_type` is ``8bit``, non-ASCII binary data is
+      converted back
       into bytes.  Headers with binary data are not refolded, regardless of the
       ``refold_header`` setting, since there is no way to know whether the
       binary data consists of single byte characters or multibyte characters.
diff --git a/Doc/library/email.rst b/Doc/library/email.rst
index ef5354f..a6cbbce 100644
--- a/Doc/library/email.rst
+++ b/Doc/library/email.rst
@@ -147,14 +147,15 @@ Here are the major differences between :mod:`email` version 4 and version 3:
   *Note that the version 3 names will continue to work until Python 2.6*.
 
 * The :mod:`email.mime.application` module was added, which contains the
-  :class:`MIMEApplication` class.
+  :class:`~email.mime.application.MIMEApplication` class.
 
 * Methods that were deprecated in version 3 have been removed.  These include
   :meth:`Generator.__call__`, :meth:`Message.get_type`,
   :meth:`Message.get_main_type`, :meth:`Message.get_subtype`.
 
 * Fixes have been added for :rfc:`2231` support which can change some of the
-  return types for :func:`Message.get_param` and friends.  Under some
+  return types for :func:`Message.get_param <email.message.Message.get_param>`
+  and friends.  Under some
   circumstances, values which used to return a 3-tuple now return simple strings
   (specifically, if all extended parameter segments were unencoded, there is no
   language and charset designation expected, so the return type is now a simple
@@ -163,23 +164,24 @@ Here are the major differences between :mod:`email` version 4 and version 3:
 
 Here are the major differences between :mod:`email` version 3 and version 2:
 
-* The :class:`FeedParser` class was introduced, and the :class:`Parser` class
-  was implemented in terms of the :class:`FeedParser`.  All parsing therefore is
+* The :class:`~email.parser.FeedParser` class was introduced, and the
+  :class:`~email.parser.Parser` class was implemented in terms of the
+  :class:`~email.parser.FeedParser`.  All parsing therefore is
   non-strict, and parsing will make a best effort never to raise an exception.
   Problems found while parsing messages are stored in the message's *defect*
   attribute.
 
 * All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
   have been removed.  These include the *_encoder* argument to the
-  :class:`MIMEText` constructor, the :meth:`Message.add_payload` method, the
-  :func:`Utils.dump_address_pair` function, and the functions :func:`Utils.decode`
-  and :func:`Utils.encode`.
+  :class:`~email.mime.text.MIMEText` constructor, the
+  :meth:`Message.add_payload` method, the :func:`Utils.dump_address_pair`
+  function, and the functions :func:`Utils.decode` and :func:`Utils.encode`.
 
 * New :exc:`DeprecationWarning`\ s have been added to:
   :meth:`Generator.__call__`, :meth:`Message.get_type`,
   :meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict*
-  argument to the :class:`Parser` class.  These are expected to be removed in
-  future versions.
+  argument to the :class:`~email.parser.Parser` class.  These are expected to
+  be removed in future versions.
 
 * Support for Pythons earlier than 2.3 has been removed.
 
@@ -187,53 +189,61 @@ Here are the differences between :mod:`email` version 2 and version 1:
 
 * The :mod:`email.Header` and :mod:`email.Charset` modules have been added.
 
-* The pickle format for :class:`Message` instances has changed. Since this was
-  never (and still isn't) formally defined, this isn't considered a backward
-  incompatibility.  However if your application pickles and unpickles
-  :class:`Message` instances, be aware that in :mod:`email` version 2,
-  :class:`Message` instances now have private variables *_charset* and
-  *_default_type*.
+* The pickle format for :class:`~email.message.Message` instances has changed.
+  Since this was never (and still isn't) formally defined, this isn't
+  considered a backward incompatibility.  However if your application pickles
+  and unpickles :class:`~email.message.Message` instances, be aware that in
+  :mod:`email` version 2, :class:`~email.message.Message` instances now have
+  private variables *_charset* and *_default_type*.
 
-* Several methods in the :class:`Message` class have been deprecated, or their
-  signatures changed.  Also, many new methods have been added.  See the
-  documentation for the :class:`Message` class for details.  The changes should be
-  completely backward compatible.
+* Several methods in the :class:`~email.message.Message` class have been
+  deprecated, or their signatures changed.  Also, many new methods have been
+  added.  See the documentation for the :class:`~email.message.Message` class
+  for details.  The changes should be completely backward compatible.
 
 * The object structure has changed in the face of :mimetype:`message/rfc822`
-  content types.  In :mod:`email` version 1, such a type would be represented by a
-  scalar payload, i.e. the container message's :meth:`is_multipart` returned
-  false, :meth:`get_payload` was not a list object, but a single :class:`Message`
-  instance.
+  content types.  In :mod:`email` version 1, such a type would be represented
+  by a scalar payload, i.e. the container message's
+  :meth:`~email.message.Message.is_multipart` returned false,
+  :meth:`~email.message.Message.get_payload` was not a list object, but a
+  single :class:`~email.message.Message` instance.
 
   This structure was inconsistent with the rest of the package, so the object
   representation for :mimetype:`message/rfc822` content types was changed.  In
   :mod:`email` version 2, the container *does* return ``True`` from
-  :meth:`is_multipart`, and :meth:`get_payload` returns a list containing a single
-  :class:`Message` item.
-
-  Note that this is one place that backward compatibility could not be completely
-  maintained.  However, if you're already testing the return type of
-  :meth:`get_payload`, you should be fine.  You just need to make sure your code
-  doesn't do a :meth:`set_payload` with a :class:`Message` instance on a container
-  with a content type of :mimetype:`message/rfc822`.
-
-* The :class:`Parser` constructor's *strict* argument was added, and its
-  :meth:`parse` and :meth:`parsestr` methods grew a *headersonly* argument.  The
-  *strict* flag was also added to functions :func:`email.message_from_file` and
-  :func:`email.message_from_string`.
-
-* :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten`
-  instead.  The :class:`Generator` class has also grown the :meth:`clone` method.
-
-* The :class:`DecodedGenerator` class in the :mod:`email.Generator` module was
-  added.
-
-* The intermediate base classes :class:`MIMENonMultipart` and
-  :class:`MIMEMultipart` have been added, and interposed in the class hierarchy
-  for most of the other MIME-related derived classes.
-
-* The *_encoder* argument to the :class:`MIMEText` constructor has been
-  deprecated.  Encoding  now happens implicitly based on the *_charset* argument.
+  :meth:`~email.message.Message.is_multipart`, and
+  :meth:`~email.message.Message.get_payload` returns a list containing a single
+  :class:`~email.message.Message` item.
+
+  Note that this is one place that backward compatibility could not be
+  completely maintained.  However, if you're already testing the return type of
+  :meth:`~email.message.Message.get_payload`, you should be fine.  You just need
+  to make sure your code doesn't do a :meth:`~email.message.Message.set_payload`
+  with a :class:`~email.message.Message` instance on a container with a content
+  type of :mimetype:`message/rfc822`.
+
+* The :class:`~email.parser.Parser` constructor's *strict* argument was added,
+  and its :meth:`~email.parser.Parser.parse` and
+  :meth:`~email.parser.Parser.parsestr` methods grew a *headersonly* argument.
+  The *strict* flag was also added to functions :func:`email.message_from_file`
+  and :func:`email.message_from_string`.
+
+* :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten
+  <email.generator.Generator.flatten>` instead.  The
+  :class:`~email.generator.Generator` class has also grown the
+  :meth:`~email.generator.Generator.clone` method.
+
+* The :class:`~email.generator.DecodedGenerator` class in the
+  :mod:`email.generator` module was added.
+
+* The intermediate base classes
+  :class:`~email.mime.nonmultipart.MIMENonMultipart` and
+  :class:`~email.mime.multipart.MIMEMultipart` have been added, and interposed
+  in the class hierarchy for most of the other MIME-related derived classes.
+
+* The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor
+  has been deprecated.  Encoding  now happens implicitly based on the
+  *_charset* argument.
 
 * The following functions in the :mod:`email.Utils` module have been deprecated:
   :func:`dump_address_pairs`, :func:`decode`, and :func:`encode`.  The following
@@ -266,17 +276,22 @@ package has the following differences:
 
 * :func:`messageFromFile` has been renamed to :func:`message_from_file`.
 
-The :class:`Message` class has the following differences:
+The :class:`~email.message.Message` class has the following differences:
 
-* The method :meth:`asString` was renamed to :meth:`as_string`.
+* The method :meth:`asString` was renamed to
+  :meth:`~email.message.Message.as_string`.
 
-* The method :meth:`ismultipart` was renamed to :meth:`is_multipart`.
+* The method :meth:`ismultipart` was renamed to
+  :meth:`~email.message.Message.is_multipart`.
 
-* The :meth:`get_payload` method has grown a *decode* optional argument.
+* The :meth:`~email.message.Message.get_payload` method has grown a *decode*
+  optional argument.
 
-* The method :meth:`getall` was renamed to :meth:`get_all`.
+* The method :meth:`getall` was renamed to
+  :meth:`~email.message.Message.get_all`.
 
-* The method :meth:`addheader` was renamed to :meth:`add_header`.
+* The method :meth:`addheader` was renamed to
+  :meth:`~email.message.Message.add_header`.
 
 * The method :meth:`gettype` was renamed to :meth:`get_type`.
 
@@ -284,48 +299,57 @@ The :class:`Message` class has the following differences:
 
 * The method :meth:`getsubtype` was renamed to :meth:`get_subtype`.
 
-* The method :meth:`getparams` was renamed to :meth:`get_params`. Also, whereas
-  :meth:`getparams` returned a list of strings, :meth:`get_params` returns a list
-  of 2-tuples, effectively the key/value pairs of the parameters, split on the
-  ``'='`` sign.
+* The method :meth:`getparams` was renamed to
+  :meth:`~email.message.Message.get_params`. Also, whereas :meth:`getparams`
+  returned a list of strings, :meth:`~email.message.Message.get_params` returns
+  a list of 2-tuples, effectively the key/value pairs of the parameters, split
+  on the ``'='`` sign.
 
-* The method :meth:`getparam` was renamed to :meth:`get_param`.
+* The method :meth:`getparam` was renamed to
+  :meth:`~email.message.Message.get_param`.
 
-* The method :meth:`getcharsets` was renamed to :meth:`get_charsets`.
+* The method :meth:`getcharsets` was renamed to
+  :meth:`~email.message.Message.get_charsets`.
 
-* The method :meth:`getfilename` was renamed to :meth:`get_filename`.
+* The method :meth:`getfilename` was renamed to
+  :meth:`~email.message.Message.get_filename`.
 
-* The method :meth:`getboundary` was renamed to :meth:`get_boundary`.
+* The method :meth:`getboundary` was renamed to
+  :meth:`~email.message.Message.get_boundary`.
 
-* The method :meth:`setboundary` was renamed to :meth:`set_boundary`.
+* The method :meth:`setboundary` was renamed to
+  :meth:`~email.message.Message.set_boundary`.
 
 * The method :meth:`getdecodedpayload` was removed.  To get similar
-  functionality, pass the value 1 to the *decode* flag of the get_payload()
-  method.
+  functionality, pass the value 1 to the *decode* flag of the
+  :meth:`~email.message.Message.get_payload` method.
 
 * The method :meth:`getpayloadastext` was removed.  Similar functionality is
-  supported by the :class:`DecodedGenerator` class in the :mod:`email.generator`
-  module.
+  supported by the :class:`~email.generator.DecodedGenerator` class in the
+  :mod:`email.generator` module.
 
 * The method :meth:`getbodyastext` was removed.  You can get similar
-  functionality by creating an iterator with :func:`typed_subpart_iterator` in the
-  :mod:`email.iterators` module.
+  functionality by creating an iterator with
+  :func:`~email.iterators.typed_subpart_iterator` in the :mod:`email.iterators`
+  module.
 
-The :class:`Parser` class has no differences in its public interface. It does
-have some additional smarts to recognize :mimetype:`message/delivery-status`
-type messages, which it represents as a :class:`Message` instance containing
-separate :class:`Message` subparts for each header block in the delivery status
-notification [#]_.
+The :class:`~email.parser.Parser` class has no differences in its public
+interface. It does have some additional smarts to recognize
+:mimetype:`message/delivery-status` type messages, which it represents as a
+:class:`~email.message.Message` instance containing separate
+:class:`~email.message.Message` subparts for each header block in the delivery
+status notification [#]_.
 
-The :class:`Generator` class has no differences in its public interface.  There
-is a new class in the :mod:`email.generator` module though, called
-:class:`DecodedGenerator` which provides most of the functionality previously
-available in the :meth:`Message.getpayloadastext` method.
+The :class:`~email.generator.Generator` class has no differences in its public
+interface.  There is a new class in the :mod:`email.generator` module though,
+called :class:`~email.generator.DecodedGenerator` which provides most of the
+functionality previously available in the :meth:`Message.getpayloadastext`
+method.
 
 The following modules and classes have been changed:
 
-* The :class:`MIMEBase` class constructor arguments *_major* and *_minor* have
-  changed to *_maintype* and *_subtype* respectively.
+* The :class:`~email.mime.base.MIMEBase` class constructor arguments *_major*
+  and *_minor* have changed to *_maintype* and *_subtype* respectively.
 
 * The ``Image`` class/module has been renamed to ``MIMEImage``.  The *_minor*
   argument has been renamed to *_subtype*.
@@ -338,7 +362,8 @@ The following modules and classes have been changed:
   but that clashed with the Python standard library module :mod:`rfc822` on some
   case-insensitive file systems.
 
-  Also, the :class:`MIMEMessage` class now represents any kind of MIME message
+  Also, the :class:`~email.mime.message.MIMEMessage` class now represents any
+  kind of MIME message
   with main type :mimetype:`message`.  It takes an optional argument *_subtype*
   which is used to set the MIME subtype.  *_subtype* defaults to
   :mimetype:`rfc822`.
@@ -348,8 +373,8 @@ The following modules and classes have been changed:
 :mod:`email.utils` module.
 
 The ``MsgReader`` class/module has been removed.  Its functionality is most
-closely supported in the :func:`body_line_iterator` function in the
-:mod:`email.iterators` module.
+closely supported in the :func:`~email.iterators.body_line_iterator` function
+in the :mod:`email.iterators` module.
 
 .. rubric:: Footnotes
 
diff --git a/Doc/library/email.util.rst b/Doc/library/email.util.rst
index bad0b24..f75975e 100644
--- a/Doc/library/email.util.rst
+++ b/Doc/library/email.util.rst
@@ -49,8 +49,8 @@ There are several useful utilities provided in the :mod:`email.utils` module:
 
    This method returns a list of 2-tuples of the form returned by ``parseaddr()``.
    *fieldvalues* is a sequence of header field values as might be returned by
-   :meth:`Message.get_all`.  Here's a simple example that gets all the recipients
-   of a message::
+   :meth:`Message.get_all <email.message.Message.get_all>`.  Here's a simple
+   example that gets all the recipients of a message::
 
       from email.utils import getaddresses
 
@@ -187,10 +187,11 @@ There are several useful utilities provided in the :mod:`email.utils` module:
 .. function:: collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')
 
    When a header parameter is encoded in :rfc:`2231` format,
-   :meth:`Message.get_param` may return a 3-tuple containing the character set,
+   :meth:`Message.get_param <email.message.Message.get_param>` may return a
+   3-tuple containing the character set,
    language, and value.  :func:`collapse_rfc2231_value` turns this into a unicode
    string.  Optional *errors* is passed to the *errors* argument of :class:`str`'s
-   :func:`encode` method; it defaults to ``'replace'``.  Optional
+   :func:`~str.encode` method; it defaults to ``'replace'``.  Optional
    *fallback_charset* specifies the character set to use if the one in the
    :rfc:`2231` header is not known by Python; it defaults to ``'us-ascii'``.