[gentoo-dev] [PATCH 0/2] vim-spell.eclass: improvements.

[gentoo-dev] [PATCH 0/2] vim-spell.eclass: improvements.

[Patrice Clement]

Hi everyone

I'm working on solving https://bugs.gentoo.org/469414 but realised much of the
eclass documentation isn't up to our standards. Here's a few commits to fix
that oversight.

Please review.

Thanks!

Patrice Clement (2):
  vim-spell.eclass: document functions using Gentoo documentation tags.
  vim-spell.eclass: document variables using Gentoo documentation tags.

 eclass/vim-spell.eclass | 66 ++++++++++++++++++++++++++++++-------------------
 1 file changed, 41 insertions(+), 25 deletions(-)

-- 
2.13.0

[gentoo-dev] [PATCH 1/2] vim-spell.eclass: document functions using Gentoo documentation tags.

[Patrice Clement]

---
 eclass/vim-spell.eclass | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/eclass/vim-spell.eclass b/eclass/vim-spell.eclass
index 0a3ef952a87..1b0f93c264d 100644
--- a/eclass/vim-spell.eclass
+++ b/eclass/vim-spell.eclass
@@ -1,12 +1,13 @@
-# Copyright 1999-2011 Gentoo Foundation
+# Copyright 1999-2017 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
 
-#
-# Original Author: Ciaran McCreesh <ciaranm@gentoo.org>
-# Maintainers:     Vim Herd <vim@gentoo.org>
-# Purpose:         Simplify installing spell files for vim7
-#
-
+# @ECLASS: vim-spell.eclass
+# @MAINTAINER:
+# Vim Maintainers <vim@gentoo.org>
+# @AUTHOR:
+# Ciaran McCreesh <ciaranm@gentoo.org>
+# @BLURB: Eclass for managing Vim spell files.
+# @DESCRIPTION:
 # How to make a vim spell file package using prebuilt spell lists
 # from upstream (${CODE} is the language's two letter code):
 #
@@ -21,9 +22,9 @@
 #
 # * Upload the tarball to the Gentoo mirrors.
 #
-# * (for now) Add your spell file to package.mask next to the other vim7
-#   things. The vim herd will handle unmasking your spell packages when vim7
-#   comes out of package.mask.
+# * Add your spell file to package.mask next to the other vim things. Vim
+#   Project members will handle unmasking your spell packages when vim comes out
+#   of package.mask.
 #
 # * Create the app-vim/vim-spell-${CODE} package. You should base your ebuild
 #   upon app-vim/vim-spell-en. You will need to change VIM_SPELL_LANGUAGE,
@@ -52,7 +53,7 @@
 # Don't forget to update your package as necessary.
 #
 # If there isn't an upstream-provided pregenerated spell file for your language
-# yet, read :help spell.txt from inside vim7 for instructions on how to create
+# yet, read :help spell.txt from inside vim for instructions on how to create
 # spell files. It's best to let upstream know if you've generated spell files
 # for another language rather than keeping them Gentoo-specific.
 
@@ -77,6 +78,9 @@ if [[ -z "${HOMEPAGE}" ]] ; then
 	HOMEPAGE="http://www.vim.org/"
 fi
 
+# @FUNCTION: vim-spell_src_install
+# @DESCRIPTION:
+# Install Vim spell files.
 vim-spell_src_install() {
 	target="/usr/share/vim/vimfiles/spell/"
 	dodir "${target}"
@@ -103,6 +107,9 @@ vim-spell_src_install() {
 	[[ -z "${had_spell_file}" ]] && die "Didn't install any spell files?"
 }
 
+# @FUNCTION: vim-spell_pkg_postinst
+# @DESCRIPTION:
+# Display installed Vim spell files.
 vim-spell_pkg_postinst() {
 	has "${EAPI:-0}" 0 1 2 && ! use prefix && EROOT="${ROOT}"
 	target="/usr/share/vim/vimfiles/spell/"
-- 
2.13.0

[gentoo-dev] [PATCH 2/2] vim-spell.eclass: document variables using Gentoo documentation tags.

[Patrice Clement]

---
 eclass/vim-spell.eclass | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/eclass/vim-spell.eclass b/eclass/vim-spell.eclass
index 1b0f93c264d..8c1b6314ed8 100644
--- a/eclass/vim-spell.eclass
+++ b/eclass/vim-spell.eclass
@@ -68,23 +68,34 @@ 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: DESCRIPTION
+# @DESCRIPTION:
+# Default DESCRIPTION for Vim spell ebuilds.
+: ${DESCRIPTION:="vim spell files: ${VIM_SPELL_LANGUAGE} (${VIM_SPELL_LOCALE})"}
 
-DESCRIPTION="vim spell files: ${VIM_SPELL_LANGUAGE} (${VIM_SPELL_CODE})"
+# @ECLASS-VARIABLE: HOMEPAGE
+# @DESCRIPTION:
+# Default HOMEPAGE for Vim spell ebuilds.
+: ${HOMEPAGE:="https://www.vim.org"}
 
-if [[ -z "${HOMEPAGE}" ]] ; then
-	HOMEPAGE="http://www.vim.org/"
-fi
+# @ECLASS-VARIABLE: VIM_SPELL_LOCALE
+# @INTERNAL
+# @DESCRIPTION:
+# Locale for the current ebuild.
+: ${VIM_SPELL_LOCALE:="${PN/vim-spell-/}"}
+
+# @ECLASS-VARIABLE: VIM_SPELL_DIRECTORY
+# @INTERNAL
+# @DESCRIPTION:
+# Path to Vim spell directory files.
+: ${VIM_SPELL_DIRECTORY:="/usr/share/vim/vimfiles/spell/"}
 
 # @FUNCTION: vim-spell_src_install
 # @DESCRIPTION:
 # Install 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
@@ -112,15 +123,13 @@ vim-spell_src_install() {
 # Display 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}.}"
+	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}"
-- 
2.13.0

Re: [gentoo-dev] [PATCH 2/2] vim-spell.eclass: document variables using Gentoo documentation tags.

[Michał Górny]

W dniu sob, 19.08.2017 o godzinie 14∶53 +0200, użytkownik Patrice
Clement napisał:
> ---
>  eclass/vim-spell.eclass | 37 +++++++++++++++++++++++--------------
>  1 file changed, 23 insertions(+), 14 deletions(-)
> 
> diff --git a/eclass/vim-spell.eclass b/eclass/vim-spell.eclass
> index 1b0f93c264d..8c1b6314ed8 100644
> --- a/eclass/vim-spell.eclass
> +++ b/eclass/vim-spell.eclass
> @@ -68,23 +68,34 @@ 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: DESCRIPTION
> +# @DESCRIPTION:
> +# Default DESCRIPTION for Vim spell ebuilds.
> +: ${DESCRIPTION:="vim spell files: ${VIM_SPELL_LANGUAGE} (${VIM_SPELL_LOCALE})"}

Wouldn't it be better to declare it after you default VIM_SPELL_*?

Also, is VIM_SPELL_LANGUAGE documented? I don't see it.

>  
> -DESCRIPTION="vim spell files: ${VIM_SPELL_LANGUAGE} (${VIM_SPELL_CODE})"
> +# @ECLASS-VARIABLE: HOMEPAGE
> +# @DESCRIPTION:
> +# Default HOMEPAGE for Vim spell ebuilds.
> +: ${HOMEPAGE:="https://www.vim.org"}
>  
> -if [[ -z "${HOMEPAGE}" ]] ; then
> -	HOMEPAGE="http://www.vim.org/"
> -fi
> +# @ECLASS-VARIABLE: VIM_SPELL_LOCALE
> +# @INTERNAL

Is it really internal? It looks like something that the ebuild might
override in the past.

> +# @DESCRIPTION:
> +# Locale for the current ebuild.
> +: ${VIM_SPELL_LOCALE:="${PN/vim-spell-/}"}
> +
> +# @ECLASS-VARIABLE: VIM_SPELL_DIRECTORY
> +# @INTERNAL
> +# @DESCRIPTION:
> +# Path to Vim spell directory files.
> +: ${VIM_SPELL_DIRECTORY:="/usr/share/vim/vimfiles/spell/"}
>  
>  # @FUNCTION: vim-spell_src_install
>  # @DESCRIPTION:
>  # Install 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
> @@ -112,15 +123,13 @@ vim-spell_src_install() {
>  # Display 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}.}"
> +	for f in "${EROOT}/${VIM_SPELL_DIRECTORY}/${VIM_SPELL_LOCALE}".*.spl ; do enc="${f##*/${VIM_SPELL_LOCALE}.}"

I suppose the combining of two lines was accidental. As a side note,
EROOT ends with /.

>  		enc="${enc%.spl}"
>  		[[ -z "${enc}" ]] && continue
>  		elog "    ${enc}"

-- 
Best regards,
Michał Górny