Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers

[Jani Nikula <jani.nikula@linux.intel.com>]

On Wed, 14 Feb 2018, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> There is a simple fix, though. Make inline comments to accept a dot:
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index fee8952037b1..06d7f3f2c094 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
>  my $doc_content = $doc_com_body . '(.*)';
>  my $doc_block = $doc_com . 'DOC:\s*(.*)?';
>  my $doc_inline_start = '^\s*/\*\*\s*$';
> -my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
> +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
>  my $doc_inline_end = '^\s*\*/\s*$';
>  my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
>  my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
>
> That requires a small change at the inline parameters, though:
>
> diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c b/drivers/gpu/drm/i915/intel_dpio_phy.c
> index 76473e9836c6..c8e9e44e5981 100644
> --- a/drivers/gpu/drm/i915/intel_dpio_phy.c
> +++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
> @@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
>  	 */
>  	struct {
>  		/**
> -		 * @port: which port maps to this channel.
> +		 * @channel.port: which port maps to this channel.
>  		 */
>  		enum port port;
>  	} channel[2];

Perhaps it would be slightly more elegant to be able to leave out
"channel." here and deduce that from the context... but the above
matches what you'd write in the higher level struct comment, and
produces the same output. It works and it's really simple. I like it.

Please submit this as a proper patch, with

Tested-by: Jani Nikula <jani.nikula@intel.com>

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center