Re: [PATCH v2] mei: intel_lb_mei_interface.h: mark struct member with kernel-doc

[Randy Dunlap <rdunlap@infradead.org>]

On 10/19/25 12:30 AM, Usyskin, Alexander wrote:
>> Subject: [PATCH v2] mei: intel_lb_mei_interface.h: mark struct member with
>> kernel-doc
>>
>> Use correct kernel-doc notation to prevent 3 kernel-doc warnings.
>> @push_payload is a struct member here, not a function, so use '@'
>> and ':' in its description.
>>
>> Warning: intel_lb_mei_interface.h:55 Incorrect use of kernel-doc format:
>>  * push_payload - Sends a payload to the authentication firmware
>> Warning: intel_lb_mei_interface.h:67 Invalid param:
>>  * @dev: Device struct corresponding to the mei device
>>  * @type: Payload type (see &enum intel_lb_type)
>>  * @flags: Payload flags bitmap (e.g. %INTEL_LB_FLAGS_IS_PERSISTENT)
>>  * @payload: Pointer to payload buffer
>>  * @payload_size: Payload buffer size in bytes
>>  * * Return: 0 success, negative errno value on transport failure,
>>  *         positive status returned by firmware */
>>  int (*push_payload)(struct device *dev, u32 type, u32 flags, const void
>>  *payload, size_t payload_size)
>> Warning: intel_lb_mei_interface.h:67 struct member '* @dev: Device struct
>>  corresponding to the mei device * @type: Payload type (see &enum
>>  intel_lb_type' not described in 'intel_lb_component_ops'
>>
> 
> Not sure about the right format here but this patch makes things better.

Yeah, we don't have a way to document callbacks in kernel-doc.

@push_payload is just a struct member here, not a function.
And the callback parameters aren't struct members. I just
didn't remove them since it's nice to have them documented
and this is the most logical/central place to do that
(most of this IMO).


> Acked-by: Alexander Usyskin <alexander.usyskin@intel.com>
> 
>> Fixes: 741eeabb7c78 ("mei: late_bind: add late binding component driver")
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> Reviewed-by: Petr Vorel <pvorel@suse.cz>
>> Reviewed-by: Nitin Gote <nitin.r.gote@intel.com>
>> ---
>> v2: reformat long kernel-doc warning lines to <= 75 chars. (Nitin)
>>
>> Cc: Alexander Usyskin <alexander.usyskin@intel.com>
>> Cc: Lucas De Marchi <lucas.demarchi@intel.com>
>> Cc: Jani Nikula <jani.nikula@linux.intel.com>
>> Cc: Rodrigo Vivi <rodrigo.vivi@intel.com>
>> Cc: Thomas Hellström <thomas.hellstrom@linux.intel.com>
>> Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
>> Cc: Tvrtko Ursulin <tursulin@ursulin.net>
>> Cc: intel-gfx@lists.freedesktop.org
>> Cc: intel-xe@lists.freedesktop.org
>> Cc: David Airlie <airlied@gmail.com>
>> Cc: Simona Vetter <simona@ffwll.ch>
>> Cc: dri-devel@lists.freedesktop.org
>> ---
>>  include/drm/intel/intel_lb_mei_interface.h |    2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> --- linux-next-20251013.orig/include/drm/intel/intel_lb_mei_interface.h
>> +++ linux-next-20251013/include/drm/intel/intel_lb_mei_interface.h
>> @@ -53,7 +53,7 @@ enum intel_lb_status {
>>   */
>>  struct intel_lb_component_ops {
>>  	/**
>> -	 * push_payload - Sends a payload to the authentication firmware
>> +	 * @push_payload: Sends a payload to the authentication firmware
>>  	 * @dev: Device struct corresponding to the mei device
>>  	 * @type: Payload type (see &enum intel_lb_type)
>>  	 * @flags: Payload flags bitmap (e.g.
>> %INTEL_LB_FLAGS_IS_PERSISTENT)

-- 
~Randy