kde5.eclass: improve documentation

Bug: https://bugs.gentoo.org/629642

1 files changed, 45 insertions, 20 deletions

diff --git a/eclass/kde5.eclass b/eclass/kde5.eclass
index a72f2d23ce4a..b05f96c78f4d 100644
--- a/eclass/kde5.eclass
+++ b/eclass/kde5.eclass
@@ -4,9 +4,22 @@
 # @ECLASS: kde5.eclass
 # @MAINTAINER:
 # kde@gentoo.org
-# @BLURB: Support eclass for KDE 5-related packages.
+# @BLURB: Support eclass for packages that follow KDE packaging conventions.
 # @DESCRIPTION:
-# The kde5.eclass provides support for building KDE 5-related packages.
+# This eclass is intended to streamline the creation of ebuilds for packages
+# that follow KDE upstream packaging conventions. It's primarily intended for
+# the three upstream release groups (Frameworks, Plasma, Applications) but
+# is also for any package that follows similar conventions.
+#
+# This eclass unconditionally inherits kde5-functions.eclass and all its public
+# functions and variables may be considered as part of this eclass's API.
+#
+# This eclass unconditionally inherits cmake-utils.eclass and all its public
+# variables and helper functions (not phase functions) may be considered as part
+# of this eclass's API.
+#
+# This eclass's phase functions are not intended to be mixed and matched, so if
+# any phase functions are overriden the version here should also be called.
 
 if [[ -z ${_KDE5_ECLASS} ]]; then
 _KDE5_ECLASS=1
@@ -35,19 +48,22 @@ EXPORT_FUNCTIONS pkg_setup pkg_nofetch src_unpack src_prepare src_configure src_
 # @ECLASS-VARIABLE: KDE_AUTODEPS
 # @DESCRIPTION:
 # If set to "false", do nothing.
-# For any other value, add a dependency on dev-qt/qtcore:5 and kde-frameworks/extra-cmake-modules:5.
+# For any other value, add dependencies on dev-qt/qtcore:5, kde-frameworks/kf-env
+# and kde-frameworks/extra-cmake-modules:5. Additionally, required blockers may
+# be set depending on the value of CATEGORY.
 : ${KDE_AUTODEPS:=true}
 
 # @ECLASS-VARIABLE: KDE_BLOCK_SLOT4
 # @DESCRIPTION:
-# This variable is used when KDE_AUTODEPS is set.
-# If set to "true", add RDEPEND block on kde-apps/${PN}:4
+# This variable only has any effect when when CATEGORY = "kde-apps" and
+# KDE_AUTODEPS is also set. If set to "true", add RDEPEND block on kde-apps/${PN}:4
 : ${KDE_BLOCK_SLOT4:=true}
 
 # @ECLASS-VARIABLE: KDE_DEBUG
 # @DESCRIPTION:
-# If set to "false", unconditionally build with -DNDEBUG.
-# Otherwise, add debug to IUSE to control building with that flag.
+# If set to "false", add -DNDEBUG (via cmake-utils_src_configure) and -DQT_NO_DEBUG
+# to CPPFLAGS.
+# Otherwise, add debug to IUSE.
 : ${KDE_DEBUG:=true}
 
 # @ECLASS-VARIABLE: KDE_DESIGNERPLUGIN
@@ -76,7 +92,7 @@ EXPORT_FUNCTIONS pkg_setup pkg_nofetch src_unpack src_prepare src_configure src_
 
 # @ECLASS-VARIABLE: KDE_DOC_DIR
 # @DESCRIPTION:
-# Defaults to "doc". Otherwise, use alternative KDE handbook path.
+# Specifies the location of the KDE handbook if not the default.
 : ${KDE_DOC_DIR:=doc}
 
 # @ECLASS-VARIABLE: KDE_QTHELP
@@ -417,7 +433,8 @@ debug-print "${LINENO} ${ECLASS} ${FUNCNAME}: SRC_URI is ${SRC_URI}"
 
 # @FUNCTION: kde5_pkg_pretend
 # @DESCRIPTION:
-# Do some basic settings
+# Checks if the active compiler meets the minimum version requirements.
+# phase function is only exported if KDE_GCC_MINIMAL is defined.
 kde5_pkg_pretend() {
 	debug-print-function ${FUNCNAME} "$@"
 	_check_gcc_version
@@ -425,7 +442,7 @@ kde5_pkg_pretend() {
 
 # @FUNCTION: kde5_pkg_setup
 # @DESCRIPTION:
-# Do some basic settings
+# Checks if the active compiler meets the minimum version requirements.
 kde5_pkg_setup() {
 	debug-print-function ${FUNCNAME} "$@"
 	_check_gcc_version
@@ -433,7 +450,9 @@ kde5_pkg_setup() {
 
 # @FUNCTION: kde5_pkg_nofetch
 # @DESCRIPTION:
-# Display package publication status
+# Intended for use in the KDE overlay. If this package matches something in
+# KDE_UNRELEASED, display a giant warning that the package has not yet been
+# released upstream and should not be used.
 kde5_pkg_nofetch() {
 	if ! _kde_is_unreleased ; then
 		return
@@ -463,7 +482,7 @@ kde5_pkg_nofetch() {
 
 # @FUNCTION: kde5_src_unpack
 # @DESCRIPTION:
-# Function for unpacking KDE 5.
+# Unpack the sources, automatically handling both release and live ebuilds.
 kde5_src_unpack() {
 	debug-print-function ${FUNCNAME} "$@"
 
@@ -480,7 +499,8 @@ kde5_src_unpack() {
 
 # @FUNCTION: kde5_src_prepare
 # @DESCRIPTION:
-# Function for preparing the KDE 5 sources.
+# Wrapper for cmake-utils_src_prepare with lots of extra logic for magic
+# handling of linguas, tests, handbook etc.
 kde5_src_prepare() {
 	debug-print-function ${FUNCNAME} "$@"
 
@@ -590,7 +610,8 @@ kde5_src_prepare() {
 
 # @FUNCTION: kde5_src_configure
 # @DESCRIPTION:
-# Function for configuring the build of KDE 5.
+# Wrapper for cmake-utils_src_configure with extra logic for magic handling of
+# handbook, tests etc.
 kde5_src_configure() {
 	debug-print-function ${FUNCNAME} "$@"
 
@@ -632,7 +653,8 @@ kde5_src_configure() {
 
 # @FUNCTION: kde5_src_compile
 # @DESCRIPTION:
-# Function for compiling KDE 5.
+# Wrapper for cmake-utils_src_compile. Currently doesn't do anything extra, but
+# is included as part of the API just in case it's needed in the future.
 kde5_src_compile() {
 	debug-print-function ${FUNCNAME} "$@"
 
@@ -641,7 +663,8 @@ kde5_src_compile() {
 
 # @FUNCTION: kde5_src_test
 # @DESCRIPTION:
-# Function for testing KDE 5.
+# Wrapper for cmake-utils_src_test with extra logic for magic handling of dbus
+# and virtualx.
 kde5_src_test() {
 	debug-print-function ${FUNCNAME} "$@"
 
@@ -672,7 +695,9 @@ kde5_src_test() {
 
 # @FUNCTION: kde5_src_install
 # @DESCRIPTION:
-# Function for installing KDE 5.
+# Wrapper for cmake-utils_src_install with extra logic to avoid compressing
+# certain types of files. For example, khelpcenter is not able to read
+# compressed handbooks.
 kde5_src_install() {
 	debug-print-function ${FUNCNAME} "$@"
 
@@ -695,7 +720,7 @@ kde5_src_install() {
 
 # @FUNCTION: kde5_pkg_preinst
 # @DESCRIPTION:
-# Function storing icon caches
+# Sets up environment variables required in kde5_pkg_postinst.
 kde5_pkg_preinst() {
 	debug-print-function ${FUNCNAME} "$@"
 
@@ -705,7 +730,7 @@ kde5_pkg_preinst() {
 
 # @FUNCTION: kde5_pkg_postinst
 # @DESCRIPTION:
-# Function to rebuild the KDE System Configuration Cache after an application has been installed.
+# Updates the various XDG caches (icon, desktop, mime) if necessary.
 kde5_pkg_postinst() {
 	debug-print-function ${FUNCNAME} "$@"
 
@@ -726,7 +751,7 @@ kde5_pkg_postinst() {
 
 # @FUNCTION: kde5_pkg_postrm
 # @DESCRIPTION:
-# Function to rebuild the KDE System Configuration Cache after an application has been removed.
+# Updates the various XDG caches (icon, desktop, mime) if necessary.
 kde5_pkg_postrm() {
 	debug-print-function ${FUNCNAME} "$@"