Fix some kernel-doc warnings in ps3.h: - add @dev to struct ps3_dma_region - don't mark a function as "struct" - add Returns: description for one function - add a short description for ps3_system_bus_set_drvdata() - correct an enum @name - move intervening "struct ps3_system_bus_device;" from between kernel-doc for ps3_dma_region_init() and the function declaration
to eliminate these warnings: Warning: arch/powerpc/include/asm/ps3.h:96 struct member 'dev' not described in 'ps3_dma_region' Warning: arch/powerpc/include/asm/ps3.h:118 struct ps3_system_bus_device; error: Cannot parse struct or union! Warning: arch/powerpc/include/asm/ps3.h:166 int ps3_mmio_region_init(struct ps3_system_bus_device *dev, struct ps3_mmio_region *r, unsigned long bus_addr, unsigned long len, enum ps3_mmio_page_size page_size); error: Cannot parse struct or union! Warning: arch/powerpc/include/asm/ps3.h:167 No description found for return value of 'ps3_mmio_region_init' Warning: arch/powerpc/include/asm/ps3.h:407 missing initial short description on line: * ps3_system_bus_set_drvdata - Warning: arch/powerpc/include/asm/ps3.h:473 Enum value 'PS3_LPM_TB_TYPE_INTERNAL' not described in enum 'ps3_lpm_tb_type' Warning: arch/powerpc/include/asm/ps3.h:473 Excess enum value '@PS3_LPM_RIGHTS_USE_TB' description in 'ps3_lpm_tb_type' This leaves struct members in several structs and function parameters in one function still undescribed. Signed-off-by: Randy Dunlap <[email protected]> --- v2: move intervening "struct ps3_system_bus_device;" Cc: Geoff Levand <[email protected]> Cc: Madhavan Srinivasan <[email protected]> Cc: Michael Ellerman <[email protected]> Cc: Nicholas Piggin <[email protected]> Cc: "Christophe Leroy (CS GROUP)" <[email protected]> Cc: [email protected] --- arch/powerpc/include/asm/ps3.h | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) --- linux-next-20251128.orig/arch/powerpc/include/asm/ps3.h +++ linux-next-20251128/arch/powerpc/include/asm/ps3.h @@ -65,6 +65,7 @@ struct ps3_dma_region_ops; /** * struct ps3_dma_region - A per device dma state variables structure + * @dev: device structure * @did: The HV device id. * @page_size: The ioc pagesize. * @region_type: The HV region type. @@ -108,15 +109,15 @@ struct ps3_dma_region_ops { dma_addr_t bus_addr, unsigned long len); }; + +struct ps3_system_bus_device; + /** * struct ps3_dma_region_init - Helper to initialize structure variables * * Helper to properly initialize variables prior to calling * ps3_system_bus_device_register. */ - -struct ps3_system_bus_device; - int ps3_dma_region_init(struct ps3_system_bus_device *dev, struct ps3_dma_region *r, enum ps3_dma_page_size page_size, enum ps3_dma_region_type region_type, void *addr, unsigned long len); @@ -156,10 +157,12 @@ struct ps3_mmio_region_ops { int (*free)(struct ps3_mmio_region *); }; /** - * struct ps3_mmio_region_init - Helper to initialize structure variables + * ps3_mmio_region_init - Helper to initialize structure variables * * Helper to properly initialize variables prior to calling * ps3_system_bus_device_register. + * + * Returns: %0 on success, %-errno on error (or BUG()) */ int ps3_mmio_region_init(struct ps3_system_bus_device *dev, @@ -405,7 +408,7 @@ static inline struct ps3_system_bus_driv } /** - * ps3_system_bus_set_drvdata - + * ps3_system_bus_set_drvdata - set driver's private data for this device * @dev: device structure * @data: Data to set */ @@ -464,7 +467,7 @@ enum ps3_lpm_rights { * enum ps3_lpm_tb_type - Type of trace buffer lv1 should use. * * @PS3_LPM_TB_TYPE_NONE: Do not use a trace buffer. - * @PS3_LPM_RIGHTS_USE_TB: Use the lv1 internal trace buffer. Must have + * @PS3_LPM_TB_TYPE_INTERNAL: Use the lv1 internal trace buffer. Must have * rights @PS3_LPM_RIGHTS_USE_TB. */
