From c2a9a645591f11761fdbe3c7f45c0ad32af97eb4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 28 Sep 2020 15:25:17 +0200 Subject: math64.h: kernel-docs: Convert some markups into normal comments There are several functions at math64.h that are also defined at div64.c. As both are included at kernel-api.rst, Sphinx 3.x complains about symbol duplication: ./lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'. Declaration is 'div_s64_rem'. ./lib/math/div64.c:104: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'. Declaration is 'div64_u64_rem'. ./lib/math/div64.c:144: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'. Declaration is 'div64_u64'. ./lib/math/div64.c:172: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'. Declaration is 'div64_s64'. In order to avoid Sphinx warnings about duplication, change the kernel-doc markups to just comments at math64.h. Reviewed-by: Vincenzo Frascino Signed-off-by: Mauro Carvalho Chehab --- include/linux/math64.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'include/linux') diff --git a/include/linux/math64.h b/include/linux/math64.h index 3381d9e33c4e..66deb1fdc2ef 100644 --- a/include/linux/math64.h +++ b/include/linux/math64.h @@ -28,7 +28,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 @@ -42,7 +42,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 @@ -56,7 +56,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 @@ -68,7 +68,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 -- cgit v1.2.3 From 1b7743912bcf2b4a9d9c96de668542156450554f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 10 Sep 2020 09:25:14 +0200 Subject: usb: docs: document altmode register/unregister functions The typec_bus.rst asks for documentation of those two functions, but they don't exist: ./drivers/usb/typec/bus.c:1: warning: 'typec_altmode_unregister_driver' not found ./drivers/usb/typec/bus.c:1: warning: 'typec_altmode_register_driver' not found Also, they're not declared on bus.c but, instead, at a header file (typec_altmode.h). So, add documentation for both functions at the header and change the kernel-doc markup under typec_bus.rst to point to the right place. While here, also place the documentation for both structs declared on typec_altmode.h at the rst file. Signed-off-by: Mauro Carvalho Chehab --- Documentation/driver-api/usb/typec_bus.rst | 8 +++++++- include/linux/usb/typec_altmode.h | 16 ++++++++++++++++ 2 files changed, 23 insertions(+), 1 deletion(-) (limited to 'include/linux') diff --git a/Documentation/driver-api/usb/typec_bus.rst b/Documentation/driver-api/usb/typec_bus.rst index 03dfa9c018b7..21c890ae17e5 100644 --- a/Documentation/driver-api/usb/typec_bus.rst +++ b/Documentation/driver-api/usb/typec_bus.rst @@ -91,10 +91,16 @@ their control. Driver API ---------- +Alternate mode structs +~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/linux/usb/typec_altmode.h + :functions: typec_altmode_driver typec_altmode_ops + Alternate mode driver registering/unregistering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/usb/typec/bus.c +.. kernel-doc:: include/linux/usb/typec_altmode.h :functions: typec_altmode_register_driver typec_altmode_unregister_driver Alternate mode driver operations diff --git a/include/linux/usb/typec_altmode.h b/include/linux/usb/typec_altmode.h index a4b65eaa0f62..5e0a7b7647c3 100644 --- a/include/linux/usb/typec_altmode.h +++ b/include/linux/usb/typec_altmode.h @@ -152,10 +152,26 @@ struct typec_altmode_driver { #define to_altmode_driver(d) container_of(d, struct typec_altmode_driver, \ driver) +/** + * typec_altmode_register_driver - registers a USB Type-C alternate mode + * device driver + * @drv: pointer to struct typec_altmode_driver + * + * These drivers will be bind to the partner alternate mode devices. They will + * handle all SVID specific communication. + */ #define typec_altmode_register_driver(drv) \ __typec_altmode_register_driver(drv, THIS_MODULE) int __typec_altmode_register_driver(struct typec_altmode_driver *drv, struct module *module); +/** + * typec_altmode_unregister_driver - unregisters a USB Type-C alternate mode + * device driver + * @drv: pointer to struct typec_altmode_driver + * + * These drivers will be bind to the partner alternate mode devices. They will + * handle all SVID specific communication. + */ void typec_altmode_unregister_driver(struct typec_altmode_driver *drv); #define module_typec_altmode_driver(__typec_altmode_driver) \ -- cgit v1.2.3 From f2c6855159228861f4552d563c13f5b194b9889f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 10 Sep 2020 10:27:17 +0200 Subject: Input: sparse-keymap: add a description for @sw Add a description for it, in order to avoids this warning: ./include/linux/input/sparse-keymap.h:43: warning: Function parameter or member 'sw' not described in 'key_entry' Signed-off-by: Mauro Carvalho Chehab --- include/linux/input/sparse-keymap.h | 1 + 1 file changed, 1 insertion(+) (limited to 'include/linux') diff --git a/include/linux/input/sparse-keymap.h b/include/linux/input/sparse-keymap.h index d25d1452dc6e..d0dddc14ebc8 100644 --- a/include/linux/input/sparse-keymap.h +++ b/include/linux/input/sparse-keymap.h @@ -20,6 +20,7 @@ * private definitions. * @code: Device-specific data identifying the button/switch * @keycode: KEY_* code assigned to a key/button + * @sw: struct with code/value used by KE_SW and KE_VSW * @sw.code: SW_* code assigned to a switch * @sw.value: Value that should be sent in an input even when KE_SW * switch is toggled. KE_VSW switches ignore this field and -- cgit v1.2.3 From 3e2ac9798e13ad1f52d735ea2ea1d252cb140ae5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 5 Oct 2020 10:58:18 +0200 Subject: PM / devfreq: remove a duplicated kernel-doc markup The update_devfreq() is also documented at devfreq.c, which has a more complete note. So, drop the duplicated markup, in order to avoid this warning: .../Documentation/driver-api/device_link.rst: WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'. Declaration is 'device_link_state'. (and to cause a problem with cross-references to it) Signed-off-by: Mauro Carvalho Chehab --- include/linux/devfreq.h | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) (limited to 'include/linux') diff --git a/include/linux/devfreq.h b/include/linux/devfreq.h index 2f4a74efa6be..121a2430d7f7 100644 --- a/include/linux/devfreq.h +++ b/include/linux/devfreq.h @@ -228,12 +228,7 @@ int devfreq_resume_device(struct devfreq *devfreq); void devfreq_suspend(void); void devfreq_resume(void); -/** - * update_devfreq() - Reevaluate the device and configure frequency - * @devfreq: the devfreq device - * - * Note: devfreq->lock must be held - */ +/* update_devfreq() - Reevaluate the device and configure frequency */ int update_devfreq(struct devfreq *devfreq); /* Helper functions for devfreq user device driver with OPP. */ -- cgit v1.2.3