vim-spell.eclass: document variables using Gentoo documentation tags.

diff --git a/eclass/vim-spell.eclass b/eclass/vim-spell.eclass
index 1b0f93c264d9419a8ce9584d6970686254a2404a..2844ea9d995e9f8eb39389f1020b97665cd50378 100644 (file)
--- a/eclass/vim-spell.eclass
+++ b/eclass/vim-spell.eclass
@@ -31,17 +31,22 @@
 #   KEYWORDS and LICENSE. Check the license carefully! The README will tell
 #   you what it is.
 #
-# * Don't forget metadata.xml. You should list vim as the herd, and yourself
-#   as the maintainer (there is no need to join the vim herd just for spell
-#   files):
+# * Don't forget metadata.xml. You should list the Vim project and yourself
+#   as maintainers. There is no need to join the Vim project just for spell
+#   files. Here's an example of a metadata.xml file:
 #
 #     <?xml version="1.0" encoding="UTF-8"?>
 #     <!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd">
 #     <pkgmetadata>
-#      <herd>vim</herd>
-#      <maintainer>
-#              <email>your-name@gentoo.org</email>
-#      </maintainer>
+#        <maintainer type="person">
+#                <email>your@email.tld</email>
+#                <name>Your Name</name>
+#        </maintainer>
+#        <maintainer type="project">
+#                <email>vim@gentoo.org</email>
+#                <name>Vim Maintainers</name>
+#        </maintainer>
+#
 #      <longdescription lang="en">
 #              Vim spell files for French (fr). Supported character sets are
 #              UTF-8 and latin1.
@@ -68,39 +73,59 @@ RDEPEND="${DEPEND}"
 SRC_URI="mirror://gentoo/${P}.tar.bz2"
 SLOT="0"
 
-if [[ -z "${VIM_SPELL_CODE}" ]] ; then
-       VIM_SPELL_CODE="${PN/vim-spell-/}"
-fi
+# @ECLASS-VARIABLE: VIM_SPELL_LANGUAGE
+# @DESCRIPTION:
+# This variable defines the language for the spell package being
+# installed.
+# The default value is "English".
+: ${VIM_SPELL_LANGUAGE:="English"}
+
+# @ECLASS-VARIABLE: VIM_SPELL_LOCALE
+# @INTERNAL
+# @DESCRIPTION:
+# This variable defines the locale for the current ebuild.
+# The default value is ${PN} stripped of the "vim-spell-" string.
+: ${VIM_SPELL_LOCALE:="${PN/vim-spell-/}"}
+
+# @ECLASS-VARIABLE: VIM_SPELL_DIRECTORY
+# @INTERNAL
+# @DESCRIPTION:
+# This variable defines the path to Vim spell files.
+: ${VIM_SPELL_DIRECTORY:="${EPREFIX}/usr/share/vim/vimfiles/spell/"}
 
-DESCRIPTION="vim spell files: ${VIM_SPELL_LANGUAGE} (${VIM_SPELL_CODE})"
+# @ECLASS-VARIABLE: DESCRIPTION
+# @DESCRIPTION:
+# This variable defines the DESCRIPTION for Vim spell ebuilds.
+: ${DESCRIPTION:="vim spell files: ${VIM_SPELL_LANGUAGE} (${VIM_SPELL_LOCALE})"}
 
-if [[ -z "${HOMEPAGE}" ]] ; then
-       HOMEPAGE="http://www.vim.org/"
-fi
+# @ECLASS-VARIABLE: HOMEPAGE
+# @DESCRIPTION:
+# This variable defines the HOMEPAGE for Vim spell ebuilds.
+: ${HOMEPAGE:="https://www.vim.org"}
 
 # @FUNCTION: vim-spell_src_install
 # @DESCRIPTION:
-# Install Vim spell files.
+# This function installs Vim spell files.
 vim-spell_src_install() {
-       target="/usr/share/vim/vimfiles/spell/"
-       dodir "${target}"
-       insinto "${target}"
+       dodir "${VIM_SPELL_DIRECTORY}"
+       insinto "${VIM_SPELL_DIRECTORY}"
 
-       had_spell_file=
-       for f in *.spl ; do
+       local had_spell_file=
+       local f
+       for f in *.spl; do
                if [[ -f "${f}" ]]; then
                        doins "${f}"
                        had_spell_file="yes"
                fi
        done
 
-       for f in *.sug ; do
+       for f in *.sug; do
                if [[ -f "${f}" ]]; then
                        doins "${f}"
                fi
        done
 
-       for f in README* ; do
+       for f in README*; do
                dodoc "${f}"
        done
 
@@ -109,18 +134,18 @@ vim-spell_src_install() {
 
 # @FUNCTION: vim-spell_pkg_postinst
 # @DESCRIPTION:
-# Display installed Vim spell files.
+# This function displays installed Vim spell files.
 vim-spell_pkg_postinst() {
        has "${EAPI:-0}" 0 1 2 && ! use prefix && EROOT="${ROOT}"
-       target="/usr/share/vim/vimfiles/spell/"
        echo
        elog "To enable ${VIM_SPELL_LANGUAGE} spell checking, use"
-       elog "    :setlocal spell spelllang=${VIM_SPELL_CODE}"
+       elog "    :setlocal spell spelllang=${VIM_SPELL_LOCALE}"
        echo
        elog "The following (Vim internal, not file) encodings are supported for"
        elog "this language:"
-       for f in "${EROOT}/${target}/${VIM_SPELL_CODE}".*.spl ; do
-               enc="${f##*/${VIM_SPELL_CODE}.}"
+       local f enc
+       for f in "${EROOT}${VIM_SPELL_DIRECTORY}/${VIM_SPELL_LOCALE}".*.spl; do
+               enc="${f##*/${VIM_SPELL_LOCALE}.}"
                enc="${enc%.spl}"
                [[ -z "${enc}" ]] && continue
                elog "    ${enc}"