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

[Anshuman Khandual]

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@xxxxxxxxxxxxx>
> ---
> v2: rebase & resend
> v3: rebase & resend
> 
> Cc: James Clark <james.clark@xxxxxxx>
> Cc: Tao Zhang <quic_taozha@xxxxxxxxxxx>
> Cc: Suzuki K Poulose <suzuki.poulose@xxxxxxx>
> Cc: coresight@xxxxxxxxxxxxxxxx
> Cc: Danilo Krummrich <dakr@xxxxxxxxxx>
> Cc: Mike Leach <mike.leach@xxxxxxx>
> Cc: Leo Yan <leo.yan@xxxxxxx>
> Cc: linux-arm-kernel@xxxxxxxxxxxxxxxxxxx
> ---
>  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 ?

./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'
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'