eclass/sword-module.eclass: update SRC_URI, expand a bit, clean up

1. The old version expected versioned source archives to have been
   manually uploaded to the Gentoo mirror network by package
   maintainers. This is no longer allowed, or indeed possible for most
   Gentoo developers. Instead, use the SRC_URI arrow mechanism to
   version archives fetched directly from upstream. SWORD Project
   updates their modules quite infrequently so it isn't really necessary
   to worry the file having changed between looking the version number
   up on the module page and fetching the archive for digest generation,
   and while users who do not use Gentoo mirrors will see digest
   conflicts when an update does occur, this would effectively encourage
   them to notify maintainers whenever a new version is released;
2. If SWORD_MODULE is not set, attempt to generate it from PN by
   stripping the prefix 'sword-'. This will allow explicit declarations
   of SWORD_MODULE to be removed from all app-dicts/sword-* ebuilds
   currently in the tree;
3. Add the optional variable SWORD_MINIMUM_VERSION to specify the lowest
   version of app-text/sword supported by the module at hand;
4. Remove redundant declarations of HOMEPAGE and IUSE;
5. app-arch/unzip is now in BDEPEND rather than DEPEND;
6. As a consequence of the above, enforce the use of EAPI-7 in ebuilds
   inheriting this eclass. Those in the tree have all already been
   updated to that EAPI version;
7. Remove redundant references to ${S} from doins() calls;
8. Add eclassdoc blocks.

No revision change in the end because all the changes should be
backwards-compatible.

Closes: https://bugs.gentoo.org/637882
Signed-off-by: Marek Szuba <marecki@gentoo.org>

1 files changed, 77 insertions, 15 deletions

diff --git a/eclass/sword-module.eclass b/eclass/sword-module.eclass
index c66c9987e9fe..2ae58d1e51bc 100644
--- a/eclass/sword-module.eclass
+++ b/eclass/sword-module.eclass
@@ -1,33 +1,95 @@
 # Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
+# @ECLASS: sword-module.eclass
+# @MAINTAINER:
+# Marek Szuba <marecki@gentoo.org>
+# @SUPPORTED_EAPIS: 7
+# @BLURB: Simplify installation of SWORD modules
+# @DESCRIPTION:
+# This eclass provides dependencies, ebuild environment and the src_install
+# function common to all app-text/sword modules published by the SWORD Project.
 #
-# eclass to simplify installation of Sword modules
-# Bugs to marecki@gentoo.org
+# Note that as of 2020-07-26 module archives published by SWORD are still
+# not versioned and it is necessary to look at respective module pages in
+# order to see what versions the currently available files are. Once
+# a module file has been replicated to the Gentoo mirror network it will be
+# versioned and remain available even after upstream has changed their
+# version, however users not using mirrors will encounter hash conflicts
+# on updated modules. Should that happen, please notify the relevant
+# package maintainers that a new version is available.
 #
+# @EXAMPLE:
+# sword-Personal-1.0.ebuild, a typical ebuild using sword-module.eclass:
+#
+# @CODE
+# EAPI=7
+#
+# SWORD_MINIMUM_VERSION="1.5.1a"
+#
+# inherit sword-module
+#
+# DESCRIPTION="SWORD module for storing one's own commentary"
+# HOMEPAGE="https://crosswire.org/sword/modules/ModInfo.jsp?modName=Personal"
+# LICENSE="public-domain"
+# KEYWORDS="~amd64 ~ppc ~x86"
+#
+# @CODE
 
-HOMEPAGE="http://www.crosswire.org/sword/modules/"
+case ${EAPI:-0} in
+	0|1|2|3|4|5|6)
+		die "Unsupported EAPI=${EAPI} (too old) for ${ECLASS}"
+		;;
+	7)
+		;;
+	*)
+		die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
+		;;
+esac
 
-# Sword packages are generally released as FooBar.zip in their 'rawzip' form
-# The files are also unversioned, so the packager will need to rename the
-# original file to something else and host it somewhere to avoid breaking
-# the digest when new versions are released.
+# @ECLASS-VARIABLE: SWORD_MINIMUM_VERSION
+# @DEFAULT_UNSET
+# @PRE_INHERIT
+# @DESCRIPTION:
+# If set to a non-null value, specifies the minimum version of app-text/sword
+# the module requires. This will be included in RDEPEND. If null or unset,
+# the dependency will be unversioned.
+# Needs to be set before the inherit line.
 
-SRC_URI="mirror://gentoo/${SWORD_MODULE}-${PV}.zip"
+# @ECLASS-VARIABLE: SWORD_MODULE
+# @PRE_INHERIT
+# @DESCRIPTION:
+# Case-sensitive name of the SWORD-Project module to install. If unset
+# or null, use the name produced by removing the prefix 'sword-' from PN.
+# Needs to be set before the inherit line.
+: ${SWORD_MODULE:=${PN#sword-}}
+
+EXPORT_FUNCTIONS src_install
+
+# Unless overridden at ebuild level, append version to the name of the file
+# fetched from upstream and let the Gentoo mirror network take care of
+# persisting the versioned archive.
+SRC_URI="https://crosswire.org/ftpmirror/pub/sword/packages/rawzip/${SWORD_MODULE}.zip -> ${SWORD_MODULE}-${PV}.zip"
 
 SLOT="0"
-IUSE=""
 
+# Module archives contain no top-level directory.
 S="${WORKDIR}"
 
-RDEPEND="app-text/sword"
-DEPEND="app-arch/unzip"
+if [[ ${SWORD_MINIMUM_VERSION} ]]; then
+	RDEPEND=">=app-text/sword-${SWORD_MINIMUM_VERSION}"
+else
+	RDEPEND="app-text/sword"
+fi
+
+BDEPEND="app-arch/unzip"
 
+# @FUNCTION: sword-module_src_install
+# @DESCRIPTION:
+# Install all the module files into directories used by app-text/sword.
 sword-module_src_install() {
 	insinto /usr/share/sword/modules
-	doins -r "${S}"/modules/*
+	doins -r modules/*
 	insinto /usr/share/sword/mods.d
-	doins "${S}"/mods.d/*
+	doins mods.d/*
 }
-
-EXPORT_FUNCTIONS src_install