Mailing List Archive

>>>>> On Sun, 15 May 2022, Mike Pagano wrote:

> +# @FUNCTION: check_zlibinflate
> +# @DESCRIPTION:
> +# helper function to make sure a ZLIB_INFLATE configuration
> +# has the requried symbols

s/requried/required/

Also, eclass-to-manpage will format won't respect the line breaks but
format @DESCRIPTION as a paragraph, so there should be a full stop at
the end of the sentence.

> +# See https://bugs.gentoo.org/27882
> check_zlibinflate() {
> if ! use kernel_linux; then
> die "${FUNCNAME}() called on non-Linux system, please fix the ebuild"

>>>>> On Sun, 15 May 2022, Ulrich Mueller wrote:

>>>>> On Sun, 15 May 2022, Mike Pagano wrote:
>> +# @FUNCTION: check_zlibinflate
>> +# @DESCRIPTION:
>> +# helper function to make sure a ZLIB_INFLATE configuration
>> +# has the requried symbols

> s/requried/required/

> Also, eclass-to-manpage will format won't respect the line breaks but
> format @DESCRIPTION as a paragraph,

Sorry, seems that I wasn't awake yet when writing this. The sentence
should read:

eclass-to-manpage won't respect the line breaks but will format
@DESCRIPTION as a paragraph,

> so there should be a full stop at the end of the sentence.

>> +# See https://bugs.gentoo.org/27882
>> check_zlibinflate() {
>> if ! use kernel_linux; then
>> die "${FUNCNAME}() called on non-Linux system, please fix the ebuild"

Updates based on Ulm's review. Thanks for the review.

Signed-off-by: Mike Pagano <mpagano@gentoo.org>
---
eclass/linux-info.eclass | 35 ++++++++++++++++++++++++++++++-----
1 file changed, 30 insertions(+), 5 deletions(-)

diff --git a/eclass/linux-info.eclass b/eclass/linux-info.eclass
index d2003874d..7e130062a 100644
--- a/eclass/linux-info.eclass
+++ b/eclass/linux-info.eclass
@@ -169,10 +169,9 @@ set_arch_to_portage() {
# Set the env ARCH to match what the package manager expects.
set_arch_to_pkgmgr() { export ARCH=$(tc-arch); }

-# qeinfo "Message"
-# -------------------
-# qeinfo is a quiet einfo call when EBUILD_PHASE
-# should not have visible output.
+# @FUNCTION: qout
+# @DESCRIPTION:
+# qout <einfo | ewarn | eerror> is a quiet call when EBUILD_PHASE should not have visible output.
qout() {
local outputmsg type
type=${1}
@@ -186,8 +185,21 @@ qout() {
[ -n "${outputmsg}" ] && ${type} "${outputmsg}"
}

+# @FUNCTION: qeinfo
+# @DESCRIPTION:
+# qeinfo is a quiet einfo call when EBUILD_PHASE should not have visible output.
qeinfo() { qout einfo "${@}" ; }
+
+# @FUNCTION: qewarn
+# @DESCRIPTION:
+# qewarn is a quiet ewarn call when EBUILD_PHASE
+# should not have visible output.
qewarn() { qout ewarn "${@}" ; }
+
+# @FUNCTION: qeerror
+# @DESCRIPTION:
+# qeerror is a quiet error call when EBUILD_PHASE
+# should not have visible output.
qeerror() { qout eerror "${@}" ; }

# File Functions
@@ -269,6 +281,10 @@ getfilevar_noexec() {
# config is available at all.
_LINUX_CONFIG_EXISTS_DONE=

+# @FUNCTION: linux_config_qa_check
+# @INTERNAL
+# @DESCRIPTION:
+# Helper funciton which returns an error before the function argument is run if no config exists
linux_config_qa_check() {
local f="$1"
if [ -z "${_LINUX_CONFIG_EXISTS_DONE}" ]; then
@@ -438,6 +454,9 @@ kernel_is() {
"${1:-${KV_MAJOR:-0}}.${2:-${KV_MINOR:-0}}.${3:-${KV_PATCH:-0}}"
}

+# @FUNCTION: get_makefile_extract_function
+# @INTERNAL
+# @DESCRIPTION:
# Check if the Makefile is valid for direct parsing.
# Check status results:
# - PASS, use 'getfilevar' to extract values
@@ -453,7 +472,10 @@ get_makefile_extract_function() {
echo "${mkfunc}"
}

-# internal variable, so we know to only print the warning once
+# @ECLASS_VARIABLE: get_version_warning_done
+# @INTERNAL
+# @DESCRIPTION:
+# Internal variable, so we know to only print the warning once.
get_version_warning_done=

# @FUNCTION: get_version
@@ -870,6 +892,9 @@ check_extra_config() {
export LINUX_CONFIG_EXISTS_DONE="${old_LINUX_CONFIG_EXISTS_DONE}"
}

+# @FUNCTION: check_zlibinflate
+# @DESCRIPTION:
+# Function to make sure a ZLIB_INFLATE configuration has the required symbols.
check_zlibinflate() {
if ! use kernel_linux; then
die "${FUNCNAME}() called on non-Linux system, please fix the ebuild"
--
2.35.1

> +# @FUNCTION: qout
> +# @DESCRIPTION:
> +# qout <einfo | ewarn | eerror> is a quiet call when EBUILD_PHASE
> # should not have visible output.

The devmanual says that @USAGE is also required for eclass functions [0]. This
is applicable in a few cases, I'm just highlighting one here.

OTOH lots of eclass functions have left out @USAGE, and the tooling around
html/man page generation also appears to treat it as optional. So it could be
that the devmanual is wrong here.

-- Thomas

[0]: https://devmanual.gentoo.org/eclass-writing/index.html#eclass-functions

>>>>> On Mon, 16 May 2022, Thomas Bracht Laumann Jespersen wrote:

>> +# @FUNCTION: qout
>> +# @DESCRIPTION:
>> +# qout <einfo | ewarn | eerror> is a quiet call when EBUILD_PHASE
>> # should not have visible output.

> The devmanual says that @USAGE is also required for eclass functions
> [0]. This is applicable in a few cases, I'm just highlighting one
> here.

@USAGE is required if the function accepts any arguments. This is
similar to @RETURN, and is clear from the examples in [0]. For example,
jmake_src_compile at the bottom of the page doesn't have a @USAGE line.

> OTOH lots of eclass functions have left out @USAGE, and the tooling
> around html/man page generation also appears to treat it as optional.

Which is correct AFAICS.

> So it could be that the devmanual is wrong here.

> [0]: https://devmanual.gentoo.org/eclass-writing/index.html#eclass-functions

> On 14 May 2022, at 23:59, Mike Pagano <mpagano@gentoo.org> wrote:
>
> Document functions which did not have any
> documentation or was not formatted to gentoo
> specifications
>
> Signed-off-by: Mike Pagano <mpagano@gentoo.org>
> ---
> eclass/linux-info.eclass | 38 ++++++++++++++++++++++++++++++++++----
> 1 file changed, 34 insertions(+), 4 deletions(-)
> [snip]

Just wanted to say thanks for putting the work in on eclassdocs and the other bits
you've been doing with the eclasses recently.

Cheers!

On 5/16/22 08:19, Mike Pagano wrote:
> Updates based on Ulm's review. Thanks for the review.
>
> Signed-off-by: Mike Pagano <mpagano@gentoo.org>
> ---
> eclass/linux-info.eclass | 35 ++++++++++++++++++++++++++++++-----
> 1 file changed, 30 insertions(+), 5 deletions(-)
>
> diff --git a/eclass/linux-info.eclass b/eclass/linux-info.eclass
> index d2003874d..7e130062a 100644
> --- a/eclass/linux-info.eclass
> +++ b/eclass/linux-info.eclass
> @@ -169,10 +169,9 @@ set_arch_to_portage() {
> # Set the env ARCH to match what the package manager expects.
> set_arch_to_pkgmgr() { export ARCH=$(tc-arch); }
>
> -# qeinfo "Message"
> -# -------------------
> -# qeinfo is a quiet einfo call when EBUILD_PHASE
> -# should not have visible output.
> +# @FUNCTION: qout
> +# @DESCRIPTION:
> +# qout <einfo | ewarn | eerror> is a quiet call when EBUILD_PHASE should not have visible output.
> qout() {
> local outputmsg type
> type=${1}
> @@ -186,8 +185,21 @@ qout() {
> [ -n "${outputmsg}" ] && ${type} "${outputmsg}"
> }
>
> +# @FUNCTION: qeinfo
> +# @DESCRIPTION:
> +# qeinfo is a quiet einfo call when EBUILD_PHASE should not have visible output.
> qeinfo() { qout einfo "${@}" ; }
> +
> +# @FUNCTION: qewarn
> +# @DESCRIPTION:
> +# qewarn is a quiet ewarn call when EBUILD_PHASE
> +# should not have visible output.
> qewarn() { qout ewarn "${@}" ; }
> +
> +# @FUNCTION: qeerror
> +# @DESCRIPTION:
> +# qeerror is a quiet error call when EBUILD_PHASE
> +# should not have visible output.
> qeerror() { qout eerror "${@}" ; }
>
> # File Functions
> @@ -269,6 +281,10 @@ getfilevar_noexec() {
> # config is available at all.
> _LINUX_CONFIG_EXISTS_DONE=
>
> +# @FUNCTION: linux_config_qa_check
> +# @INTERNAL
> +# @DESCRIPTION:
> +# Helper funciton which returns an error before the function argument is run if no config exists
> linux_config_qa_check() {
> local f="$1"
> if [ -z "${_LINUX_CONFIG_EXISTS_DONE}" ]; then
> @@ -438,6 +454,9 @@ kernel_is() {
> "${1:-${KV_MAJOR:-0}}.${2:-${KV_MINOR:-0}}.${3:-${KV_PATCH:-0}}"
> }
>
> +# @FUNCTION: get_makefile_extract_function
> +# @INTERNAL
> +# @DESCRIPTION:
> # Check if the Makefile is valid for direct parsing.
> # Check status results:
> # - PASS, use 'getfilevar' to extract values
> @@ -453,7 +472,10 @@ get_makefile_extract_function() {
> echo "${mkfunc}"
> }
>
> -# internal variable, so we know to only print the warning once
> +# @ECLASS_VARIABLE: get_version_warning_done
> +# @INTERNAL
> +# @DESCRIPTION:
> +# Internal variable, so we know to only print the warning once.
> get_version_warning_done=
>
> # @FUNCTION: get_version
> @@ -870,6 +892,9 @@ check_extra_config() {
> export LINUX_CONFIG_EXISTS_DONE="${old_LINUX_CONFIG_EXISTS_DONE}"
> }
>
> +# @FUNCTION: check_zlibinflate
> +# @DESCRIPTION:
> +# Function to make sure a ZLIB_INFLATE configuration has the required symbols.
> check_zlibinflate() {
> if ! use kernel_linux; then
> die "${FUNCNAME}() called on non-Linux system, please fix the ebuild"

committed

On 5/16/22 18:57, Sam James wrote:
>
>
>> On 14 May 2022, at 23:59, Mike Pagano <mpagano@gentoo.org> wrote:
>>
>> Document functions which did not have any
>> documentation or was not formatted to gentoo
>> specifications
>>
>> Signed-off-by: Mike Pagano <mpagano@gentoo.org>
>> ---
>> eclass/linux-info.eclass | 38 ++++++++++++++++++++++++++++++++++----
>> 1 file changed, 34 insertions(+), 4 deletions(-)
>> [snip]
>
> Just wanted to say thanks for putting the work in on eclassdocs and the other bits
> you've been doing with the eclasses recently.
>
> Cheers!


Thanks, Sam. You are the perfect representation of how collaboration in Gentoo can be great.