diff --git a/Modules/FindKDE4.cmake b/Modules/FindKDE4.cmake
index 220906b2de..4d289f6221 100644
--- a/Modules/FindKDE4.cmake
+++ b/Modules/FindKDE4.cmake
@@ -5,27 +5,214 @@
 FindKDE4
 --------
 
+.. note::
+
+  This module is specifically intended for KDE version 4, which is obsolete
+  and no longer maintained.  For modern application development using KDE
+  technologies with CMake, use a newer version of KDE, and refer to the
+  `KDE documentation
+  <https://develop.kde.org/docs/getting-started/building/cmake-build/>`_.
+
+Finds the KDE 4 installation:
+
+.. code-block:: cmake
+
+  find_package(KDE4 [...])
+
+This module is a wrapper around the following upstream KDE 4 modules:
+
+``FindKDE4Internal.cmake``
+
+  Upstream internal module, which finds the KDE 4 include directories,
+  libraries, and KDE-specific preprocessor tools.  It provides usage
+  requirements for building KDE 4 software and defines several helper
+  commands to simplify working with KDE 4 in CMake.
+
+``KDE4Macros.cmake``
+  Upstream utility module that defines all additional KDE4-specific
+  commands to use KDE 4 in CMake.  For example:
+  ``kde4_automoc()``, ``kde4_add_executable()``, ``kde4_add_library()``,
+  ``kde4_add_ui_files()``, ``kde4_add_ui3_files()``,
+  ``kde4_add_kcfg_files()``, ``kde4_add_kdeinit_executable()``, etc.
+
+Upstream KDE 4 modules are installed by the KDE 4 distribution package in
+``$KDEDIRS/share/apps/cmake/modules/``.  This path is automatically
+appended to the :variable:`CMAKE_MODULE_PATH` variable when calling
+``find_package(KDE4)``, so any additional KDE 4 modules can be included in
+the project with :command:`include`.  For example:
+
+``KDE4Defaults.cmake``
+  Upstream internal module that sets some CMake options which are useful,
+  but not required for building KDE 4 software.  If these settings should
+  be used, include this module after finding KDE 4:
+
+  .. code-block:: cmake
+
+    find_package(KDE4)
+    include(KDE4Defaults)
+
+For usage details, refer to the upstream KDE 4 documentation.  For example,
+at the top of the ``FindKDE4Internal`` module a complete documentation is
+available for all variables and commands these modules provide.
+
+Hints
+^^^^^
+
+This module accepts the following variables before calling the
+``find_package(KDE4)``:
+
+``ENV{KDEDIRS}``
+  Environment variable containing the path to the KDE 4 installation.
+
+KDE 4 is searched in the following directories in the given order:
+
+* :variable:`CMAKE_INSTALL_PREFIX` variable
+* ``KDEDIRS`` environment variable
+* ``/opt/kde4`` path
+
+Examples
+^^^^^^^^
+
+Example: Basic Usage
+""""""""""""""""""""
+
+Finding KDE 4 as required and using it in CMake:
+
+.. code-block:: cmake
+
+  find_package(KDE4 REQUIRED)
+
+  set(sources main.cpp mywidget.cpp mypart.cpp)
+
+  # The kde4_*() commands are provided by the KDE4Macros module, which is
+  # included automatically by FindKDE4, if KDE4 is found:
+  kde4_automoc(${sources})
+  kde4_add_executable(example ${sources})
+
+  target_include_directories(example PRIVATE ${KDE4_INCLUDES})
+  target_link_libraries(example PRIVATE ${KDE4_KDEUI_LIBS} ${KDE4_KPARTS_LIBS})
+
+  install(TARGETS example DESTINATION ${CMAKE_INSTALL_BINDIR})
+  install(FILES kfoo.desktop DESTINATION ${XDG_APPS_DIR})
+
+Example: Full Featured Example
+""""""""""""""""""""""""""""""
+
+In the following example this module is used to find KDE 4 installation.
+
+.. code-block:: cmake
+
+  project(kfoo)
+
+  find_package(KDE4 REQUIRED)
+
+  # Append path from where to include local project modules if any:
+  list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
+
+  include_directories(${KDE4_INCLUDE_DIRS})
+  add_definitions(${KDE4_DEFINITIONS})
+
+  set(sources main.cpp myappl.cpp view.cpp)
+
+  # If Qt designer UI files version 3 or 4 are available add them to the
+  # sources variable:
+  kde4_add_ui_files(sources maindialog.ui logindialog.ui)
+  kde4_add_ui3_files(sources printerdlg.ui previewdlg.ui)
+
+  # If there are files for the kconfig_compiler add them this way:
+  kde4_add_kcfg_files(sources settings.kcfg)
+
+  # When everything is listed, probably automoc is wanted:
+  kde4_automoc(${sources})
+
+  # Finally, specify what to build:
+  kde4_add_executable(kfoo ${sources})
 
 
-Find KDE4 and provide all necessary variables and macros to compile
-software for it.  It looks for KDE 4 in the following directories in
-the given order:
+The ``kde4_add_executable()`` command is a slightly extended version of the
+CMake command :command:`add_executable`.  Additionally, it does some more
+``RPATH`` handling and supports the ``KDE4_ENABLE_FINAL`` variable.  The
+first argument is the name of the executable followed by a list of source
+files.  If a library needs to be created instead of an executable, the
+``kde4_add_library()`` can be used.  It is an extended version of the
+:command:`add_library` command.  It adds support for the
+``KDE4_ENABLE_FINAL`` variable and under Windows it adds the
+``-DMAKE_KFOO_LIB`` to the compile flags.
 
-::
+.. code-block:: cmake
 
-  CMAKE_INSTALL_PREFIX
-  KDEDIRS
-  /opt/kde4
+  find_package(KDE4 REQUIRED)
 
+  # ...
 
+  kde4_add_library(kfoo ${sources})
 
-Please look in ``FindKDE4Internal.cmake`` and ``KDE4Macros.cmake`` for more
-information.  They are installed with the KDE 4 libraries in
-$KDEDIRS/share/apps/cmake/modules/.
+  # Optionally, set the library version number if needed:
+  set_target_properties(kfoo PROPERTIES VERSION 5.0.0 SOVERSION 5)
 
-Author: Alexander Neundorf <neundorf@kde.org>
+KDE is very modular, so if a KPart, a control center module, or an ioslave
+needs to be created, here's how to do it:
+
+.. code-block:: cmake
+
+  find_package(KDE4 REQUIRED)
+  # ...
+  kde4_add_plugin(kfoo ${sources})
+
+Now, the application/library/plugin probably needs to link to some
+libraries.  For this use the standard :command:`target_link_libraries`
+command.  For every KDE library there are variables available in the form
+of ``KDE4_FOO_LIBS``.  Use them to get also all depending libraries:
+
+.. code-block:: cmake
+
+  target_link_libraries(kfoo ${KDE4_KDEUI_LIBS} ${KDE4_KIO_LIBS})
+
+Example: The kdeinit Executable
+"""""""""""""""""""""""""""""""
+
+In the following example, the so called kdeinit executable is created.
+The ``kde4_add_kdeinit_executable()`` command creates both an executable
+with the given name and a library with the given name prefixed with
+``kdeinit_``.  The :command:`target_link_libraries` command adds all
+required libraries to the ``kdeinit_kbar`` library, and then links the
+``kbar`` against the ``kdeinit_kbar``:
+
+.. code-block:: cmake
+
+  find_package(KDE4 REQUIRED)
+
+  # ...
+
+  kde4_add_kdeinit_executable(kbar ${kbarSources})
+  target_link_libraries(kdeinit_kbar ${KDE4_KIO_LIBS})
+  target_link_libraries(kbar kdeinit_kbar)
+
+  install(TARGETS kbar DESTINATION ${CMAKE_INSTALL_BINDIR})
+  install(TARGETS kdeinit_kbar DESTINATION ${CMAKE_INSTALL_LIBDIR})
+
+Example: Removing Compile Definitions
+"""""""""""""""""""""""""""""""""""""
+
+Sometimes, a default compile definition passed to the compiler needs to be
+removed.  The :command:`remove_definitions` command can be used.  For
+example, by default, the KDE4 build system sets the ``-DQT_NO_STL`` flag.
+If the project code uses some of the Qt STL compatibility layer, this flag
+should be removed:
+
+.. code-block:: cmake
+
+  find_package(KDE4 REQUIRED)
+
+  add_definitions(${KDE4_DEFINITIONS})
+
+  # ...
+
+  remove_definitions(-DQT_NO_STL)
 #]=======================================================================]
 
+# Author: Alexander Neundorf <neundorf@kde.org>
+
 # If Qt3 has already been found, fail.
 if(QT_QT_LIBRARY)
   if(KDE4_FIND_REQUIRED)