Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <479bd33b-f68c-aceb-49e0-122a2e99d5c1@gmail.com>
Date:   Tue, 27 Sep 2022 15:32:07 +0700
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.13.1
Subject: Re: [PATCH] overflow: Fix kern-doc markup for functions
Content-Language: en-US
To:     Kees Cook <keescook@chromium.org>, Jonathan Corbet <corbet@lwn.net>
Cc:     Akira Yokosawa <akiyks@gmail.com>, linux-doc@vger.kernel.org,
        linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org
References: <20220926194713.1806917-1-keescook@chromium.org>
From:   Bagas Sanjaya <bagasdotme@gmail.com>
In-Reply-To: <20220926194713.1806917-1-keescook@chromium.org>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 9/27/22 02:47, Kees Cook wrote:
> diff --git a/include/linux/overflow.h b/include/linux/overflow.h
> index 58eb34aa2af9..4b5b3ec91233 100644
> --- a/include/linux/overflow.h
> +++ b/include/linux/overflow.h
> @@ -51,7 +51,8 @@ static inline bool __must_check __must_check_overflow(bool overflow)
>  	return unlikely(overflow);
>  }
>  
> -/** check_add_overflow() - Calculate addition with overflow checking
> +/**
> + * check_add_overflow - Calculate addition with overflow checking
>   *
>   * @a: first addend
>   * @b: second addend
> @@ -66,7 +67,8 @@ static inline bool __must_check __must_check_overflow(bool overflow)
>  #define check_add_overflow(a, b, d)	\
>  	__must_check_overflow(__builtin_add_overflow(a, b, d))
>  
> -/** check_sub_overflow() - Calculate subtraction with overflow checking
> +/**
> + * check_sub_overflow - Calculate subtraction with overflow checking
>   *
>   * @a: minuend; value to subtract from
>   * @b: subtrahend; value to subtract from @a
> @@ -81,7 +83,8 @@ static inline bool __must_check __must_check_overflow(bool overflow)
>  #define check_sub_overflow(a, b, d)	\
>  	__must_check_overflow(__builtin_sub_overflow(a, b, d))
>  
> -/** check_mul_overflow() - Calculate multiplication with overflow checking
> +/**
> + * check_mul_overflow - Calculate multiplication with overflow checking
>   *
>   * @a: first factor
>   * @b: second factor
> @@ -96,7 +99,8 @@ static inline bool __must_check __must_check_overflow(bool overflow)
>  #define check_mul_overflow(a, b, d)	\
>  	__must_check_overflow(__builtin_mul_overflow(a, b, d))
>  
> -/** check_shl_overflow() - Calculate a left-shifted value and check overflow
> +/**
> + * check_shl_overflow - Calculate a left-shifted value and check overflow
>   *
>   * @a: Value to be shifted
>   * @s: How many bits left to shift
> @@ -104,15 +108,16 @@ static inline bool __must_check __must_check_overflow(bool overflow)
>   *
>   * Computes *@d = (@a << @s)
>   *
> - * Returns true if '*d' cannot hold the result or when 'a << s' doesn't
> + * Returns true if '*@d' cannot hold the result or when '@a << @s' doesn't
>   * make sense. Example conditions:
> - * - 'a << s' causes bits to be lost when stored in *d.
> - * - 's' is garbage (e.g. negative) or so large that the result of
> - *   'a << s' is guaranteed to be 0.
> - * - 'a' is negative.
> - * - 'a << s' sets the sign bit, if any, in '*d'.
>   *
> - * '*d' will hold the results of the attempted shift, but is not
> + * - '@a << @s' causes bits to be lost when stored in *@d.
> + * - '@s' is garbage (e.g. negative) or so large that the result of
> + *   '@a << @s' is guaranteed to be 0.
> + * - '@a' is negative.
> + * - '@a << @s' sets the sign bit, if any, in '*@d'.
> + *
> + * '*@d' will hold the results of the attempted shift, but is not
>   * considered "safe for use" if true is returned.
>   */
>  #define check_shl_overflow(a, s, d) __must_check_overflow(({		\
> @@ -176,7 +181,7 @@ static inline bool __must_check __must_check_overflow(bool overflow)
>  			      __same_type(n, T))
>  
>  /**
> - * size_mul() - Calculate size_t multiplication with saturation at SIZE_MAX
> + * size_mul - Calculate size_t multiplication with saturation at SIZE_MAX
>   *
>   * @factor1: first factor
>   * @factor2: second factor
> @@ -196,7 +201,7 @@ static inline size_t __must_check size_mul(size_t factor1, size_t factor2)
>  }
>  
>  /**
> - * size_add() - Calculate size_t addition with saturation at SIZE_MAX
> + * size_add - Calculate size_t addition with saturation at SIZE_MAX
>   *
>   * @addend1: first addend
>   * @addend2: second addend
> @@ -216,7 +221,7 @@ static inline size_t __must_check size_add(size_t addend1, size_t addend2)
>  }
>  
>  /**
> - * size_sub() - Calculate size_t subtraction with saturation at SIZE_MAX
> + * size_sub - Calculate size_t subtraction with saturation at SIZE_MAX
>   *
>   * @minuend: value to subtract from
>   * @subtrahend: value to subtract from @minuend
> @@ -239,7 +244,7 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend)
>  }
>  
>  /**
> - * array_size() - Calculate size of 2-dimensional array.
> + * array_size - Calculate size of 2-dimensional array.
>   *
>   * @a: dimension one
>   * @b: dimension two
> @@ -252,7 +257,7 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend)
>  #define array_size(a, b)	size_mul(a, b)
>  
>  /**
> - * array3_size() - Calculate size of 3-dimensional array.
> + * array3_size - Calculate size of 3-dimensional array.
>   *
>   * @a: dimension one
>   * @b: dimension two
> @@ -266,8 +271,8 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend)
>  #define array3_size(a, b, c)	size_mul(size_mul(a, b), c)
>  
>  /**
> - * flex_array_size() - Calculate size of a flexible array member
> - *                     within an enclosing structure.
> + * flex_array_size - Calculate size of a flexible array member
> + *                   within an enclosing structure.
>   *
>   * @p: Pointer to the structure.
>   * @member: Name of the flexible array member.
> @@ -284,7 +289,7 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend)
>  		size_mul(count, sizeof(*(p)->member) + __must_be_array((p)->member)))
>  
>  /**
> - * struct_size() - Calculate size of structure with trailing flexible array.
> + * struct_size - Calculate size of structure with trailing flexible array.
>   *
>   * @p: Pointer to the structure.
>   * @member: Name of the array member.

Hmm...

I can't apply this patch for testing. On what tree (and what commit) this
patch is based on?

Thanks.

-- 
An old man doll... just what I always wanted! - Clara