From patchwork Wed Feb 14 17:53:14 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 10219581 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 04268601C2 for ; Wed, 14 Feb 2018 17:53:28 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 018ED28D8D for ; Wed, 14 Feb 2018 17:53:28 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id EA5DA28ED0; Wed, 14 Feb 2018 17:53:27 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id D8E6C28D8D for ; Wed, 14 Feb 2018 17:53:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1161551AbeBNRxW (ORCPT ); Wed, 14 Feb 2018 12:53:22 -0500 Received: from osg.samsung.com ([64.30.133.232]:44206 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1161403AbeBNRxV (ORCPT ); Wed, 14 Feb 2018 12:53:21 -0500 Received: from localhost (localhost [127.0.0.1]) by osg.samsung.com (Postfix) with ESMTP id 785262F156; Wed, 14 Feb 2018 09:53:20 -0800 (PST) X-Virus-Scanned: Debian amavisd-new at dev.s-opensource.com Received: from osg.samsung.com ([127.0.0.1]) by localhost (localhost [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id uzD1vs9I_-B0; Wed, 14 Feb 2018 09:53:19 -0800 (PST) Received: from vento.lan (unknown [179.183.107.230]) by osg.samsung.com (Postfix) with ESMTPSA id A06F02F14D; Wed, 14 Feb 2018 09:53:17 -0800 (PST) Date: Wed, 14 Feb 2018 15:53:14 -0200 From: Mauro Carvalho Chehab To: Jani Nikula Cc: Linux Media Mailing List , Jonathan Corbet , Mauro Carvalho Chehab , Linux Doc Mailing List , "chris\@chris-wilson.co.uk" Subject: Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers Message-ID: <20180214155314.1be00577@vento.lan> In-Reply-To: <874lmjlfmg.fsf@intel.com> References: <874lmjlfmg.fsf@intel.com> Organization: Samsung X-Mailer: Claws Mail 3.15.1-dirty (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Em Wed, 14 Feb 2018 18:07:03 +0200 Jani Nikula escreveu: > On Mon, 18 Dec 2017, Mauro Carvalho Chehab wrote: > > It is possible to use nested structs like: > > > > struct { > > struct { > > void *arg1; > > } st1, st2, *st3, st4; > > }; > > > > Handling it requires to split each parameter. Change the logic > > to allow such definitions. > > > > In order to test the new nested logic, the following file > > was used to test > > Hi Mauro, resurrecting an old thread... > > So this was a great improvement to documenting nested structs. However, > it looks like it only supports describing the nested structs at the top > level comment, and fails for inline documentation comments. True. I didn't consider inline comments when I wrote the patch. We don't use inline doc tags at media. IMO, a single description block on the top works better, but yeah, it would be very good if it would support nested structs to also have inlined comments. Yet, on a quick hack: The alternative would be a way more complex: to teach the code with starts at: If ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) { About how to handle with inlined structs/enums at inlined comments. Thanks, Mauro Tested-by: Jani Nikula 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];