Received: by 10.192.165.148 with SMTP id m20csp2969846imm; Mon, 7 May 2018 04:33:45 -0700 (PDT) X-Google-Smtp-Source: AB8JxZqMPaqQPCWcw4c+U9DewyLQkhoCpgiN7cAwN7vci0qMWRIdyFfN+wtNpDy0eU6wCfEpMya+ X-Received: by 2002:a63:8f5b:: with SMTP id r27-v6mr20113849pgn.439.1525692825892; Mon, 07 May 2018 04:33:45 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1525692825; cv=none; d=google.com; s=arc-20160816; b=BbfmEmgY08CozSBxTrmvyKVeoLgNp8Y0bXJP4/frk1uxGoPIQMnnsXivuTHcZVEVYY iM0LTwFZlZ18ENwWsaVobBK0Z3NH+Bzg8+8fj/zbZr2G6Nsfdwpp7F/QKAd3p4V8QrwT q+kOIPIW6NHdrqyJyiXaQaOvGls1FTF3Pm+urpTYmzXoYLVg6hWJhKG3xOYTc8iU2oZV xIrduLo2x4PRQbfDpfz8u08Emm2XuLNGCkbqJEw4sN5I28NcxArkedtGH0R9SnLUHa7F U76wsnjCk3riInwHCxIuMni+exUw+6vV39pAfDIELWQ1b6qSNVzlrmsXJyrEilgRCOoh YaQg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:subject:cc:to:from:date :dkim-signature:arc-authentication-results; bh=WWk71Wva51AHX30uzcIfTiFjfCSCIzqvclxC2mXb6wU=; b=haPEjLeb63fQUrrRnBfGI0nooIL0CJLERtC5GQUvxxb8Vt3Iy7/AnUIjZxlCKE1GBq 3wG9XIrd5HjTGSdbIETOB12MlKfZCNWKrGMyiKkoX+9+rebmIaOmy1uzEeVpc+K21pCd BuAwhm0tCbUolfSy7oTv9iqeth74hS2EaAw5jBKpUlqkHAZiGiPZ39uZ4dcwuBS4TpXa e5U1fEB7NPhBTaLGfgEIiwBGV9vpSPQWU1TqUafqrAKrrsrRHBT56Fs2JL03mSBhGATr 0MzvmPEWs0ZE9WfUCHMR76rn6DUUcyKcltMGRkpRGvkL9PXTCWrtAF6IqIp3i0o8AP/M c6cg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=eMYYWlzJ; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id f88si22399888pfk.107.2018.05.07.04.33.31; Mon, 07 May 2018 04:33:45 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=eMYYWlzJ; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752221AbeEGLcl (ORCPT + 99 others); Mon, 7 May 2018 07:32:41 -0400 Received: from bombadil.infradead.org ([198.137.202.133]:59842 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752049AbeEGLcj (ORCPT ); Mon, 7 May 2018 07:32:39 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Content-Transfer-Encoding: Content-Type:MIME-Version:References:In-Reply-To:Message-ID:Subject:Cc:To: From:Date:Sender:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=WWk71Wva51AHX30uzcIfTiFjfCSCIzqvclxC2mXb6wU=; b=eMYYWlzJdeEdfIdMNbNsyY47T ofISnFyfqsFSump7jXY+8EzN9SdB7xexmnFdGlPyfqUASvMpgfc1cUpMIOaHh8S+z6B4H2TIAqFQV HuWtzFFIHJxlfGr0XmmMoBcrKgKSoS5sn5+2DQ+w6LR2yy/RB+ByrBx2jFRyP+/SmDqQ86yfayBOH 1UJLGZhlZR0nw0II9fyYnjIgNgU2/FEmeKKwRcC8iH4EumAlzqMWGqWOValqzEiG4euQTNo8X/xi0 T0M3JuPnyJgzD7BjUVuvekeRhmQEcnwSWkBtJY9l8gNNrrNqE0KcCGb3sPAAATZZLJcuCVGr+dPGA zhELDuKzQ==; Received: from 177.41.109.86.dynamic.adsl.gvt.net.br ([177.41.109.86] helo=vento.lan) by bombadil.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1fFeNg-0007DD-NA; Mon, 07 May 2018 11:32:37 +0000 Date: Mon, 7 May 2018 08:32:32 -0300 From: Mauro Carvalho Chehab To: Boris Brezillon Cc: Linux Doc Mailing List , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Richard Weinberger , David Woodhouse , Brian Norris , Marek Vasut , linux-mtd@lists.infradead.org Subject: Re: [PATCH 16/18] mtd: rawnand.h: use nested union kernel-doc markups Message-ID: <20180507083232.5a084ba7@vento.lan> In-Reply-To: <20180507114650.171edcc2@bbrezillon> References: <39d8d4f0e0ff5a06be0303f7f4f2eac5fb45b9ca.1525684985.git.mchehab+samsung@kernel.org> <20180507114650.171edcc2@bbrezillon> X-Mailer: Claws Mail 3.16.0 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Hi Boris, Em Mon, 7 May 2018 11:46:50 +0200 Boris Brezillon escreveu: > Hi Mauro, > > diff --git a/include/linux/mtd/rawnand.h b/include/linux/mtd/rawnand.h > > index 5dad59b31244..b986f94906df 100644 > > --- a/include/linux/mtd/rawnand.h > > +++ b/include/linux/mtd/rawnand.h > > @@ -740,8 +740,9 @@ enum nand_data_interface_type { > > > > /** > > * struct nand_data_interface - NAND interface timing > > - * @type: type of the timing > > - * @timings: The timing, type according to @type > > + * @type: type of the timing > > + * @timings: The timing, type according to @type > > + * @timings.sdr: Use it when @type is %NAND_SDR_IFACE. > > Hm, really feels weird to do that. I mean, either we describe > timings.sdr or timings, but not both. I this case, I agree that > describing timings.sdr would make more sense than generically > describing any possible entries in the timings union. This struct is funny, as the union has just one item. I assume that the original intend is to be ready to have more timing types (or you had it in the past). By the time you have a second value there, describing the union would make more sense. > Is there a simple > way we can get rid of the warning we have when not describing timings > but all of its fields? There's no direct way. It won't be hard to add a way to do it, like applying the enclosed patch with ends by declaring timings as: * @timings: -- undescribed -- IMHO, this is uglier. The way I see is that, if the embed struct/union is not interesting enough to be described, the best would be to use an anonymous one like: struct nand_data_interface { enum nand_data_interface_type type; union { struct nand_sdr_timings sdr; }; }; With the above, kernel-doc will expect a description just for @sdr. Btw, if you want to see how nested struct/union is parsed, the scripts/kernel_doc logic is at dump_struct() function. When it finds an struct, it first handles private/public by simply removing everything that it is not public from the struct, by a very simple parser. Then, it converts nested struct/union into un-nested ones. E. g. it converts: struct { union { int foo1; }; union { int foo2; } bar; } foobar; into this internal representation: struct { int foo1; union; int bar.foo2; union bar; }; Then it runs the normal un-nested struct parser. Thanks, Mauro [PATCH] don't describe nested struct timings IMHO, this is an ugly hack, but it allows having nested structs (or fields) undescribed by purpose. Signed-off-by: Mauro Carvalho Chehab diff --git a/include/linux/mtd/rawnand.h b/include/linux/mtd/rawnand.h index b986f94906df..b724c7edf532 100644 --- a/include/linux/mtd/rawnand.h +++ b/include/linux/mtd/rawnand.h @@ -741,7 +741,7 @@ enum nand_data_interface_type { /** * struct nand_data_interface - NAND interface timing * @type: type of the timing - * @timings: The timing, type according to @type + * @timings: -- undescribed -- * @timings.sdr: Use it when @type is %NAND_SDR_IFACE. */ struct nand_data_interface { diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 0057d8eafcc1..196a2107c8c1 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -390,7 +390,7 @@ my $section = $section_default; my $section_context = "Context"; my $section_return = "Return"; -my $undescribed = "-- undescribed --"; +my $undescribed = "-- undescribed --\n"; reset_state();