Merge pull request #3628 from Starbuck5/clarify-freetype-status

Clarify the status of the freetype module

Author: Starbuck5

docs/reST/ref/freetype.rst

@@ -4,18 +4,22 @@
 ======================
 
 .. module:: pygame.freetype
-   :synopsis: Enhanced pygame module for loading and rendering computer fonts
-
-| :sl:`Enhanced pygame module for loading and rendering computer fonts`
-
-The ``pygame.freetype`` module is a replacement for :mod:`pygame.font`.
-It has all of the functionality of the original, plus many new features.
-Yet is has absolutely no dependencies on the SDL_ttf library.
-It is implemented directly on the FreeType 2 library.
-The ``pygame.freetype`` module is not itself backward compatible with
-:mod:`pygame.font`.
-Instead, use the ``pygame.ftfont`` module as a drop-in replacement
-for :mod:`pygame.font`.
+   :synopsis: pygame module for loading and rendering computer fonts
+
+| :sl:`pygame module for loading and rendering computer fonts`
+
+The ``pygame.freetype`` module is an alternative to :mod:`pygame.font`.
+It is implemented directly on the FreeType 2 library, and is not
+backward compatible with :mod:`pygame.font`. :mod:`pygame.font`
+relies on the SDL_ttf library, and due to the SDL_ttf team's efforts,
+``pygame.font`` is now the better supported of our font modules.
+In new code, the use of :mod:`pygame.font` is encouraged.
+``pygame.font``, unlike ``pygame.freetype``, has support for multiline text,
+text shaping for global writing systems, and rendering emoji with color.
+
+The ``pygame.ftfont`` module exists as a limited version of
+the :mod:`pygame.font` API, running on top of ``pygame.freetype``.
+Many of the recently added font features do not work on it.
 
 All font file formats supported by FreeType can be rendered by
 ``pygame.freetype``, namely ``TTF``, Type1, ``CFF``, OpenType,

src_c/doc/freetype_doc.h

@@ -1,5 +1,5 @@
 /* Auto generated file: with make_docs.py .  Docs go in docs/reST/ref/ . */
-#define DOC_FREETYPE "Enhanced pygame module for loading and rendering computer fonts"
+#define DOC_FREETYPE "pygame module for loading and rendering computer fonts"
 #define DOC_FREETYPE_GETERROR "get_error() -> str\nget_error() -> None\nReturn the latest FreeType error"
 #define DOC_FREETYPE_GETVERSION "get_version(linked=True) -> (int, int, int)\nReturn the FreeType version"
 #define DOC_FREETYPE_INIT "init(cache_size=64, resolution=72) -> None\nInitialize the underlying FreeType library."