| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <aPEgMkJnnK7SgCMR@gmail.com>
Date: Thu, 16 Oct 2025 16:41:22 +0000
From: Vaibhav Gupta <vaibhavgupta40@...il.com>
To: Randy Dunlap <rdunlap@...radead.org>
Cc: linux-kernel@...r.kernel.org,
Jens Taprogge <jens.taprogge@...rogge.org>,
Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
industrypack-devel@...ts.sourceforge.net
Subject: Re: [PATCH v2] ipack: fix ipack.h kernel-doc warnings
On Wed, Oct 15, 2025 at 08:35:43PM -0700, Randy Dunlap wrote:
> Fix various kernel-doc warnings in ipack.h:
>
> - Remove an empty kernel-doc comment.
> - Add 2 missing struct short descriptions.
> - Fix a typo in a description.
> - Add a missing struct field description.
> - Add some missing Return descriptions.
> - Clarify one function short description.
>
> Warning: ../include/linux/ipack.h:73 Cannot find identifier on line:
> */
> Warning: ../include/linux/ipack.h:74 Cannot find identifier on line:
> struct ipack_region {
> Warning: ../include/linux/ipack.h:75 Cannot find identifier on line:
> phys_addr_t start;
> Warning: ../include/linux/ipack.h:76 Cannot find identifier on line:
> size_t size;
> Warning: ../include/linux/ipack.h:77 Cannot find identifier on line:
> };
> Warning: ../include/linux/ipack.h:78 Cannot find identifier on line:
>
> Warning: ../include/linux/ipack.h:79 Cannot find identifier on line:
> /**
> Warning: ipack.h:80 missing initial short description on line:
> * struct ipack_device
> Warning: ipack.h:163 missing initial short description on line:
> * struct ipack_bus_device
> Warning: ipack.h:130 struct member 'id_table' not described in 'ipack_driver'
> Warning: ipack.h:189 No description found for return value of 'ipack_bus_register'
> Warning: ipack.h:194 No description found for return value of 'ipack_bus_unregister' ***
> Warning: ipack.h:202 No description found for return value of 'ipack_driver_register'
> Warning: ipack.h:221 No description found for return value of 'ipack_device_init'
> Warning: ipack.h:236 No description found for return value of 'ipack_device_add'
> Warning: ipack.h:271 No description found for return value of 'ipack_get_carrier'
>
> Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
> ---
> v2: reformat patch description with indents (Vaibhav)
>
> Cc: Vaibhav Gupta <vaibhavgupta40@...il.com>
> Cc: Jens Taprogge <jens.taprogge@...rogge.org>
> Cc: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
> Cc: industrypack-devel@...ts.sourceforge.net
> ---
> include/linux/ipack.h | 23 +++++++++++++++--------
> 1 file changed, 15 insertions(+), 8 deletions(-)
>
> --- linux-next-20251013.orig/include/linux/ipack.h
> +++ linux-next-20251013/include/linux/ipack.h
> @@ -70,15 +70,13 @@ enum ipack_space {
> IPACK_SPACE_COUNT,
> };
>
> -/**
> - */
> struct ipack_region {
> phys_addr_t start;
> size_t size;
> };
>
> /**
> - * struct ipack_device
> + * struct ipack_device - subsystem representation of an IPack device
> *
> * @slot: Slot where the device is plugged in the carrier board
> * @bus: ipack_bus_device where the device is plugged to.
> @@ -89,7 +87,7 @@ struct ipack_region {
> *
> * Warning: Direct access to mapped memory is possible but the endianness
> * is not the same with PCI carrier or VME carrier. The endianness is managed
> - * by the carrier board throught bus->ops.
> + * by the carrier board through bus->ops.
> */
> struct ipack_device {
> unsigned int slot;
> @@ -124,6 +122,7 @@ struct ipack_driver_ops {
> * struct ipack_driver -- Specific data to each ipack device driver
> *
> * @driver: Device driver kernel representation
> + * @id_table: Device ID table for this driver
> * @ops: Callbacks provided by the IPack device driver
> */
> struct ipack_driver {
> @@ -161,7 +160,7 @@ struct ipack_bus_ops {
> };
>
> /**
> - * struct ipack_bus_device
> + * struct ipack_bus_device - IPack bus representation
> *
> * @dev: pointer to carrier device
> * @slots: number of slots available
> @@ -185,6 +184,8 @@ struct ipack_bus_device {
> *
> * The carrier board device should call this function to register itself as
> * available bus device in ipack.
> + *
> + * Return: %NULL on error or &struct ipack_bus_device on success
> */
> struct ipack_bus_device *ipack_bus_register(struct device *parent, int slots,
> const struct ipack_bus_ops *ops,
> @@ -192,6 +193,8 @@ struct ipack_bus_device *ipack_bus_regis
>
> /**
> * ipack_bus_unregister -- unregister an ipack bus
> + *
> + * Return: %0
> */
> int ipack_bus_unregister(struct ipack_bus_device *bus);
>
> @@ -200,6 +203,8 @@ int ipack_bus_unregister(struct ipack_bu
> *
> * Called by a ipack driver to register itself as a driver
> * that can manage ipack devices.
> + *
> + * Return: zero on success or error code on failure.
> */
> int ipack_driver_register(struct ipack_driver *edrv, struct module *owner,
> const char *name);
> @@ -215,7 +220,7 @@ void ipack_driver_unregister(struct ipac
> * function. The rest of the fields will be allocated and populated
> * during initalization.
> *
> - * Return zero on success or error code on failure.
> + * Return: zero on success or error code on failure.
> *
> * NOTE: _Never_ directly free @dev after calling this function, even
> * if it returned an error! Always use ipack_put_device() to give up the
> @@ -230,7 +235,7 @@ int ipack_device_init(struct ipack_devic
> * Add a new IPack device. The call is done by the carrier driver
> * after calling ipack_device_init().
> *
> - * Return zero on success or error code on failure.
> + * Return: zero on success or error code on failure.
> *
> * NOTE: _Never_ directly free @dev after calling this function, even
> * if it returned an error! Always use ipack_put_device() to give up the
> @@ -266,9 +271,11 @@ void ipack_put_device(struct ipack_devic
> .device = (dev)
>
> /**
> - * ipack_get_carrier - it increase the carrier ref. counter of
> + * ipack_get_carrier - try to increase the carrier ref. counter of
> * the carrier module
> * @dev: mezzanine device which wants to get the carrier
> + *
> + * Return: true on success.
> */
> static inline int ipack_get_carrier(struct ipack_device *dev)
> {
Hello Randy,
Thank you for your changes.
Acknowledged-by: Vaibhav Gupta <vaibhavgupta40@...il.com>
Hey Greg, could you please add this patch to your misc tree?
Thanks,
Vaibhav
Powered by blists - more mailing lists