Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss

[gentoo-dev] [PATCH] linux-info.eclass: Documentation updates

4 views
Skip to first unread message

Mike Pagano

unread,
May 14, 2022, 7:10:03 PM5/14/22
to
Document functions which did not have any
documentation or was not formatted to gentoo
specifications

Signed-off-by: Mike Pagano <mpa...@gentoo.org>
---
eclass/linux-info.eclass | 38 ++++++++++++++++++++++++++++++++++----
1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/eclass/linux-info.eclass b/eclass/linux-info.eclass
index d2003874d..a61ba0153 100644
--- a/eclass/linux-info.eclass
+++ b/eclass/linux-info.eclass
@@ -169,9 +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
+# @FUNCTION: qout
+# @DESCRIPTION:
+# qout <einfo | ewarn | eerror> is a quiet call when EBUILD_PHASE
# should not have visible output.
qout() {
local outputmsg type
@@ -186,8 +186,22 @@ 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 +283,11 @@ 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 +457,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 +475,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 to ensure we print a message only once
get_version_warning_done=

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

+# @FUNCTION: check_zlibinflate
+# @DESCRIPTION:
+# helper function to make sure a ZLIB_INFLATE configuration
+# has the requried symbols
+# See https://bugs.gentoo.org/27882
check_zlibinflate() {
if ! use kernel_linux; then
die "${FUNCNAME}() called on non-Linux system, please fix the ebuild"
--
2.35.1


OpenPGP_signature

Ulrich Mueller

unread,
May 15, 2022, 3:30:02 AM5/15/22
to
>>>>> 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.
signature.asc

Ulrich Mueller

unread,
May 15, 2022, 3:40:02 AM5/15/22
to
>>>>> 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

Thomas Bracht Laumann Jespersen

unread,
May 16, 2022, 3:20:03 PM5/16/22
to
> +# @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

Ulrich Mueller

unread,
May 16, 2022, 4:00:05 PM5/16/22
to
>>>>> 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
signature.asc

Mike Pagano

unread,
May 16, 2022, 7:00:02 PM5/16/22
to
On 5/16/22 08:19, Mike Pagano wrote:
> Updates based on Ulm's review. Thanks for the review.
>
> Signed-off-by: Mike Pagano <mpa...@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

Sam James

unread,
May 16, 2022, 7:00:03 PM5/16/22
to


> On 14 May 2022, at 23:59, Mike Pagano <mpa...@gentoo.org> wrote:
>
> Document functions which did not have any
> documentation or was not formatted to gentoo
> specifications
>
> Signed-off-by: Mike Pagano <mpa...@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!
signature.asc

Mike Pagano

unread,
May 16, 2022, 7:10:03 PM5/16/22
to
Thanks, Sam. You are the perfect representation of how collaboration in Gentoo can be great.
0 new messages