public inbox for linux-doc@vger.kernel.org
 help / color / mirror / Atom feed
* kernel-doc for nested structs/unions
@ 2026-02-16  1:47 Randy Dunlap
  2026-02-18  7:04 ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 3+ messages in thread
From: Randy Dunlap @ 2026-02-16  1:47 UTC (permalink / raw)
  To: Linux Documentation, Mauro Carvalho Chehab, Jonathan Corbet

Hi,

I have run into some confusing discrepancies (differences) in how
kernel-doc handles some nested unions and structs.

Examples:
in include/linux/property.h, struct property_entry, there is this
nested union:

	union {
		const void *pointer;
		union {
			u8 u8_data[sizeof(u64) / sizeof(u8)];
			u16 u16_data[sizeof(u64) / sizeof(u16)];
			u32 u32_data[sizeof(u64) / sizeof(u32)];
			u64 u64_data[sizeof(u64) / sizeof(u64)];
			const char *str[sizeof(u64) / sizeof(char *)];
		} value;
	};

Running kernel-doc -none on this file reports:

Warning: include/linux/property.h:406 struct member 'u8_data' not described in 'property_entry'
Warning: include/linux/property.h:406 struct member 'u16_data' not described in 'property_entry'
Warning: include/linux/property.h:406 struct member 'u32_data' not described in 'property_entry'
Warning: include/linux/property.h:406 struct member 'u64_data' not described in 'property_entry'
Warning: include/linux/property.h:406 struct member 'str' not described in 'property_entry'

If I follow the instructions in Documentation/doc-guide/kernel-doc.rst
for using kernel-doc with nested structs/unions, I should add @value.u8_data
etc. for these 5 missing kernel-doc entries.
However, that still fails with the same warnings as above.
Adding only @u8_data: etc. for these file struct members satisfies
kernel-doc.
Conclusion: don't use the nested union member name (contrary to
the kernel-doc documentation).

~~~~~
Now if we look at include/linux/soc/ti/knav_dma.h, there is a struct:

struct knav_dma_cfg {
	enum dma_transfer_direction direction;
	union {
		struct knav_dma_tx_cfg	tx;
		struct knav_dma_rx_cfg	rx;
	} u;
};

Running kernel-doc -none reports:
Warning: include/linux/soc/ti/knav_dma.h:127 struct member 'direction' not described in 'knav_dma_cfg'
Warning: include/linux/soc/ti/knav_dma.h:127 struct member 'u' not described in 'knav_dma_cfg'

After adding comments for @direction and @u, kernel-doc -none reports:
no problems with this struct, where the struct kernel-doc looks like:

/**
 * struct knav_dma_cfg:	Pktdma channel configuration
 * @direction:		DMA transfer information
 * @u:			@tx or @rx configuration
 * @tx:			Tx channel configuration
 * @rx:			Rx flow configuration
 */

so kernel-doc is happy with @tx and @rx without having the union name prepended.
Well, this is again: Don't use the nested member union name.
OTOH, if I do add the "u." to the @tx and @rx members,
kernel-doc is still happy (no warnings here).

~~~~~
Looking at include/asm-generic/msi.h, kernel-doc reports:

Warning: include/asm-generic/msi.h:31 struct member 'flags' not described in 'msi_alloc_info'

Easy to fix. Add that and kernel-doc is happy. Now we have:

/**
 * struct msi_alloc_info - Default structure for MSI interrupt allocation.
 * @desc:	Pointer to msi descriptor
 * @hwirq:	Associated hw interrupt number in the domain
 * @flags:	Bits from MSI_ALLOC_FLAGS_...
 * @scratchpad:	Storage for implementation specific scratch data
 *
 * Architectures can provide their own implementation by not including
 * asm-generic/msi.h into their arch specific header file.
 */
typedef struct msi_alloc_info {
	struct msi_desc			*desc;
	irq_hw_number_t			hwirq;
	unsigned long			flags;
	union {
		unsigned long		ul;
		void			*ptr;
	} scratchpad[NUM_MSI_ALLOC_SCRATCHPAD_REGS];
} msi_alloc_info_t;


Two questions here:
(1) Why are @ul and @ptr not causing kernel-doc warnings?
(1b) Should they be @scratchpad.ul and @scratchpad.ptr?
(2) Is the typedef confusing things here?

~~~~~
For include/soc/fsl/dpaa2-fd.h, kernel-doc reports:
Warning: include/soc/fsl/dpaa2-fd.h:51 struct member 'simple' not described in 'dpaa2_fd'

Adding a @simple entry satisfies kernel-doc, but isn't kernel-doc required
for @simple's struct member fields also?

Well, feels like I am rambling. I thought that I had a case of
the enclosing struct or union name being _required_, but so far all
that I have shown is that it's not required (in these cases).

-- 
~Randy

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2026-02-21  1:22 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-02-16  1:47 kernel-doc for nested structs/unions Randy Dunlap
2026-02-18  7:04 ` Mauro Carvalho Chehab
2026-02-21  1:22   ` Randy Dunlap

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox