2022-11-17 03:16:50

by Liam Beguin

Subject: [PATCH v1 1/2] math64: favor kernel-doc from header files

Fix the kernel-doc markings for div64 functions to point to the header
file instead of the lib/ directory. This avoids having implementation
specific comments in generic documentation. Furthermore, given that
some kernel-doc comments are identical, drop them from lib/math64 and
only keep there comments that add implementation details.

Signed-off-by: Liam Beguin <[email protected]>
---
Documentation/core-api/kernel-api.rst | 3 ---
include/linux/math64.h | 12 ++++++------
lib/math/div64.c | 15 ++-------------
3 files changed, 8 insertions(+), 22 deletions(-)

diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 06f4ab122697..c9412eb85552 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -171,9 +171,6 @@ Division Functions
.. kernel-doc:: include/linux/math64.h
:internal:

-.. kernel-doc:: lib/math/div64.c
- :functions: div_s64_rem div64_u64_rem div64_u64 div64_s64
-
.. kernel-doc:: lib/math/gcd.c
:export:

diff --git a/include/linux/math64.h b/include/linux/math64.h
index a14f40de1dca..1538844fcb51 100644
--- a/include/linux/math64.h
+++ b/include/linux/math64.h
@@ -29,7 +29,7 @@ static inline u64 div_u64_rem(u64 dividend, u32 divisor, u32 *remainder)
return dividend / divisor;
}

-/*
+/**
* div_s64_rem - signed 64bit divide with 32bit divisor with remainder
* @dividend: signed 64bit dividend
* @divisor: signed 32bit divisor
@@ -43,7 +43,7 @@ static inline s64 div_s64_rem(s64 dividend, s32 divisor, s32 *remainder)
return dividend / divisor;
}

-/*
+/**
* div64_u64_rem - unsigned 64bit divide with 64bit divisor and remainder
* @dividend: unsigned 64bit dividend
* @divisor: unsigned 64bit divisor
@@ -57,7 +57,7 @@ static inline u64 div64_u64_rem(u64 dividend, u64 divisor, u64 *remainder)
return dividend / divisor;
}

-/*
+/**
* div64_u64 - unsigned 64bit divide with 64bit divisor
* @dividend: unsigned 64bit dividend
* @divisor: unsigned 64bit divisor
@@ -69,7 +69,7 @@ static inline u64 div64_u64(u64 dividend, u64 divisor)
return dividend / divisor;
}

-/*
+/**
* div64_s64 - signed 64bit divide with 64bit divisor
* @dividend: signed 64bit dividend
* @divisor: signed 64bit divisor
@@ -300,7 +300,7 @@ u64 mul_u64_u64_div_u64(u64 a, u64 mul, u64 div);
#define DIV64_U64_ROUND_CLOSEST(dividend, divisor) \
({ u64 _tmp = (divisor); div64_u64((dividend) + _tmp / 2, _tmp); })

-/*
+/**
* DIV_U64_ROUND_CLOSEST - unsigned 64bit divide with 32bit divisor rounded to nearest integer
* @dividend: unsigned 64bit dividend
* @divisor: unsigned 32bit divisor
@@ -313,7 +313,7 @@ u64 mul_u64_u64_div_u64(u64 a, u64 mul, u64 div);
#define DIV_U64_ROUND_CLOSEST(dividend, divisor) \
({ u32 _tmp = (divisor); div_u64((u64)(dividend) + _tmp / 2, _tmp); })

-/*
+/**
* DIV_S64_ROUND_CLOSEST - signed 64bit divide with 32bit divisor rounded to nearest integer
* @dividend: signed 64bit dividend
* @divisor: signed 32bit divisor
diff --git a/lib/math/div64.c b/lib/math/div64.c
index 46866394fc84..55a81782e271 100644
--- a/lib/math/div64.c
+++ b/lib/math/div64.c
@@ -63,12 +63,6 @@ uint32_t __attribute__((weak)) __div64_32(uint64_t *n, uint32_t base)
EXPORT_SYMBOL(__div64_32);
#endif

-/**
- * div_s64_rem - signed 64bit divide with 64bit divisor and remainder
- * @dividend: 64bit dividend
- * @divisor: 64bit divisor
- * @remainder: 64bit remainder
- */
#ifndef div_s64_rem
s64 div_s64_rem(s64 dividend, s32 divisor, s32 *remainder)
{
@@ -89,7 +83,7 @@ s64 div_s64_rem(s64 dividend, s32 divisor, s32 *remainder)
EXPORT_SYMBOL(div_s64_rem);
#endif

-/**
+/*
* div64_u64_rem - unsigned 64bit divide with 64bit divisor and remainder
* @dividend: 64bit dividend
* @divisor: 64bit divisor
@@ -129,7 +123,7 @@ u64 div64_u64_rem(u64 dividend, u64 divisor, u64 *remainder)
EXPORT_SYMBOL(div64_u64_rem);
#endif

-/**
+/*
* div64_u64 - unsigned 64bit divide with 64bit divisor
* @dividend: 64bit dividend
* @divisor: 64bit divisor
@@ -163,11 +157,6 @@ u64 div64_u64(u64 dividend, u64 divisor)
EXPORT_SYMBOL(div64_u64);
#endif

-/**
- * div64_s64 - signed 64bit divide with 64bit divisor
- * @dividend: 64bit dividend
- * @divisor: 64bit divisor
- */
#ifndef div64_s64
s64 div64_s64(s64 dividend, s64 divisor)
{

base-commit: 59d0d52c30d4991ac4b329f049cc37118e00f5b0
--
2.37.1.223.g6a475b71f8c4

2022-11-17 17:34:31

by Randy Dunlap

Subject: Re: [PATCH v1 1/2] math64: favor kernel-doc from header files

Hi--

On 11/16/22 18:35, Liam Beguin wrote:
> Fix the kernel-doc markings for div64 functions to point to the header
> file instead of the lib/ directory. This avoids having implementation
> specific comments in generic documentation. Furthermore, given that
> some kernel-doc comments are identical, drop them from lib/math64 and
> only keep there comments that add implementation details.
>
> Signed-off-by: Liam Beguin <[email protected]>

LGTM.

Could you also fix these 2 warnings?

math64.h:126: warning: No description found for return value of 'div_u64'
math64.h:139: warning: No description found for return value of 'div_s64'

Acked-by: Randy Dunlap <[email protected]>
Tested-by: Randy Dunlap <[email protected]>

Thanks.

> ---
> Documentation/core-api/kernel-api.rst | 3 ---
> include/linux/math64.h | 12 ++++++------
> lib/math/div64.c | 15 ++-------------
> 3 files changed, 8 insertions(+), 22 deletions(-)

--
~Randy

2022-11-17 17:34:52

by Liam Beguin

Subject: Re: [PATCH v1 1/2] math64: favor kernel-doc from header files

Hi Randy,

On Thu, Nov 17, 2022 at 09:01:11AM -0800, Randy Dunlap wrote:
> Hi--
>
> On 11/16/22 18:35, Liam Beguin wrote:
> > Fix the kernel-doc markings for div64 functions to point to the header
> > file instead of the lib/ directory. This avoids having implementation
> > specific comments in generic documentation. Furthermore, given that
> > some kernel-doc comments are identical, drop them from lib/math64 and
> > only keep there comments that add implementation details.
> >
> > Signed-off-by: Liam Beguin <[email protected]>
>
> LGTM.
>
> Could you also fix these 2 warnings?
>
> math64.h:126: warning: No description found for return value of 'div_u64'
> math64.h:139: warning: No description found for return value of 'div_s64'
>

Sure, I'll look into that!

Cheers,
Liam

> Acked-by: Randy Dunlap <[email protected]>
> Tested-by: Randy Dunlap <[email protected]>
>
> Thanks.
>
> > ---
> > Documentation/core-api/kernel-api.rst | 3 ---
> > include/linux/math64.h | 12 ++++++------
> > lib/math/div64.c | 15 ++-------------
> > 3 files changed, 8 insertions(+), 22 deletions(-)
>
> --
> ~Randy