math64: favor kernel-doc from header files
PATCH v2 1/3 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.
--- Documentation/core-api/kernel-api.rst | 3 --- include/linux/math64.h | 12 ++++++------ lib/math/div64.c | 15 ++------------- 3 files changed, 8 insertions(+), 22 deletions(-)
Documentation/core-api/kernel-api.rst +0 -3
@@ -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:
include/linux/math64.h +6 -6
@@ -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
lib/math/div64.c +2 -13
@@ -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_rems64 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_s64s64 div64_s64 (s64 dividend,s64 divisor) {
base-commit: 59d0d52c30d4991ac4b329f049cc37118e00f5b0
Signature · 1 line
2.37.1.223.g6a475b71f8c4
PATCH v2 2/3 math64: add kernel-doc for DIV64_U64_ROUND_UP
Add kernel-doc for DIV64_U64_ROUND_UP so that it appears in the documentation.
--- include/linux/math64.h | 10 ++++++++++ 1 file changed, 10 insertions(+)
include/linux/math64.h +10 -0
@@ -284,6 +284,16 @@ static inline u64 mul_u64_u32_div(u64 a, u32 mul, u32 divisor)u64 mul_u64_u64_div_u64 (u64 a,u64 mul,u64 div); +/** +* DIV64_U64_ROUND_UP - unsigned 64bit divide with 64bit divisor rounded up +* @ll: unsigned 64bit dividend +* @d: unsigned 64bit divisor +* +* Divide unsigned 64bit dividend by unsigned 64bit divisor +* and round up. +* +* Return: dividend / divisor rounded up +*/ #define DIV64_U64_ROUND_UP (ll, d) \ ({ u64 _tmp = (d); div64_u64((ll) + _tmp - 1, _tmp); })
Signature · 1 line
2.37.1.223.g6a475b71f8c4
PATCH v2 3/3 math64: fix kernel-doc return value warnings
In reply to Liam BeguinFix the following kernel-doc warnings by adding a description for return values of div_[us]64.
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'
--- include/linux/math64.h | 4 ++++ 1 file changed, 4 insertions(+)
include/linux/math64.h +4 -0
@@ -120,6 +120,8 @@ extern s64 div64_s64(s64 dividend, s64 divisor);* This is the most common 64bit divide and should be used if possible, * as many 32bit archs can optimize this variant better than a full 64bit * divide. +* +* Return: dividend / divisor */ #ifndef div_u64static inline u64 div_u64 (u64 dividend,u32 divisor)
@@ -133,6 +135,8 @@ static inline u64 div_u64(u64 dividend, u32 divisor)* div_s64 - signed 64bit divide with 32bit divisor * @dividend: signed 64bit dividend * @divisor: signed 32bit divisor +* +* Return: dividend / divisor */ #ifndef div_s64static inline s64 div_s64 (s64 dividend,s32 divisor)
Signature · 1 line
2.37.1.223.g6a475b71f8c4
Quoted 6 lines · Liam Beguin
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.
Quoted 8 lines
Signed-off-by Liam Beguin <[email protected]>Acked-by Randy Dunlap <[email protected]>Tested-by Randy Dunlap <[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(-)
I've applied the series, thanks.
jon