Re: [PATCH v3] coresight: coresight.h: add '*' to kernel-doc lines

[Randy Dunlap <rdunlap@infradead.org>]

On 7/27/26 10:31 PM, Anshuman Khandual wrote:
> 
> 
> On 20/07/26 3:54 AM, Randy Dunlap wrote:
>> kernel-doc reports 2 (kernel-doc) lines in coresight.h that don't have
>> a beginning '*' in them, so fix these lines.
>>
>> Also convert struct coresight_trace_id_map to kernel-doc format to
>> remove another warning.
>>
>> Warning: include/linux/coresight.h:173 bad line:
>>   connected to @src_port. NULL until the device is created
>> Warning: include/linux/coresight.h:177 bad line:
>>   needs to be filtered.
>> Warning: include/linux/coresight.h:236 This comment starts with '/**',
>>   but isn't a kernel-doc comment.
>>
>> Fixes: ec9903d6cc34 ("coresight: Add support for trace filtering by source")
>> Fixes: d49c9cf15f89 ("coresight: Rename connection members to make the direction explicit")
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> ---
>> v2: rebase & resend
>> v3: rebase & resend
>>
>> Cc: James Clark <james.clark@arm.com>
>> Cc: Tao Zhang <quic_taozha@quicinc.com>
>> Cc: Suzuki K Poulose <suzuki.poulose@arm.com>
>> Cc: coresight@lists.linaro.org
>> Cc: Danilo Krummrich <dakr@kernel.org>
>> Cc: Mike Leach <mike.leach@arm.com>
>> Cc: Leo Yan <leo.yan@arm.com>
>> Cc: linux-arm-kernel@lists.infradead.org
>> ---
>>  include/linux/coresight.h |    6 +++---
>>  1 file changed, 3 insertions(+), 3 deletions(-)
>>
>> --- linux-next-20260717.orig/include/linux/coresight.h
>> +++ linux-next-20260717/include/linux/coresight.h
>> @@ -177,11 +177,11 @@ struct coresight_desc {
>>   * @dest_port:	destination's input port number @src_port is connected to.
>>   * @dest_fwnode: destination component's fwnode handle.
>>   * @dest_dev:	a @coresight_device representation of the component
>> -		connected to @src_port. NULL until the device is created
>> + *		connected to @src_port. NULL until the device is created
>>   * @link: Representation of the connection as a sysfs link.
>>   * @filter_src_fwnode: filter source component's fwnode handle.
>>   * @filter_src_dev: a @coresight_device representation of the component that
>> -		needs to be filtered.
>> + *		needs to be filtered.
>>   *
>>   * The full connection structure looks like this, where in_conns store
>>   * references to same connection as the source device's out_conns.
>> @@ -234,7 +234,7 @@ struct coresight_sysfs_link {
>>  #define CORESIGHT_TRACE_IDS_MAX 128
>>  
>>  /**
>> - * Trace ID map.
>> + * struct coresight_trace_id_map - Trace ID map.
>>   *
>>   * @used_ids:	Bitmap to register available (bit = 0) and in use (bit = 1) IDs.
>>   *		Initialised so that the reserved IDs are permanently marked as
>>
> 
> But still there are more warnings left in the documentation file
> even after the patch applied. Should they be fixed as well ?

Yes, I know that. Hopefully someone with expertise in this area can add a few
comments there.

> ./scripts/kernel-doc -none include/linux/coresight.h
> Warning: include/linux/coresight.h:216 struct member 'src_dev' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:216 struct member 'src_refcnt' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:216 struct member 'dest_refcnt' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:248 struct member 'cpu_map' not described in 'coresight_trace_id_map'
> Warning: include/linux/coresight.h:248 struct member 'lock' not described in 'coresight_trace_id_map'
> Warning: include/linux/coresight.h:312 struct member 'perf_sink_id_map' not described in 'coresight_device'

Note that half of these are just duplicates of the lines above.

> Warning: include/linux/coresight.h:216 struct member 'src_dev' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:216 struct member 'src_refcnt' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:216 struct member 'dest_refcnt' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:248 struct member 'cpu_map' not described in 'coresight_trace_id_map'
> Warning: include/linux/coresight.h:248 struct member 'lock' not described in 'coresight_trace_id_map'
> Warning: include/linux/coresight.h:312 struct member 'perf_sink_id_map' not described in 'coresight_device'

thanks.
-- 
~Randy