| Message ID | 20180214155314.1be00577@vento.lan (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
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.
Em Wed, 14 Feb 2018 20:20:21 +0200 Jani Nikula <jani.nikula@linux.intel.com> escreveu: > 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> Submitted. I ended by submitting as a patch series, as, when I did some tests with the examples, I found that kernel-doc have issues parsing them. Thanks, Mauro
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index fee8952037b1..e2d5cadd8d0b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1009,6 +1009,8 @@ sub dump_struct($$) { $declaration_name = $2; my $members = $3; +print "members: $members\n"; + # ignore members marked private: $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi; $members =~ s/\/\*\s*private:.*//gosi; produce: $ scripts/kernel-doc -none drivers/gpu/drm/i915/intel_dpio_phy.c members: bool dual_channel; enum dpio_phy rcomp_phy; int reset_delay; u32 pwron_mask; struct { enum port port; } channel[2]; drivers/gpu/drm/i915/intel_dpio_phy.c:154: warning: Function parameter or member 'channel.port' not described in 'bxt_ddi_phy_info' So, dump_struct() already receives the struct sanitizes without any comments inside. 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];