From patchwork Fri Jan 11 19:39:14 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 155359 Delivered-To: patch@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp946728jaa; Fri, 11 Jan 2019 11:39:17 -0800 (PST) X-Google-Smtp-Source: ALg8bN65vmDXWTGU7OMsChqiXw9artx1bDz7b2DLQgnvSOiM+O+pQorHtPJK3m7tlXLfG6XqDwtq X-Received: by 2002:a62:5c41:: with SMTP id q62mr16142717pfb.171.1547235557116; Fri, 11 Jan 2019 11:39:17 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1547235557; cv=none; d=google.com; s=arc-20160816; b=d06hNXx17qKnvNn7I/3zG4JVjfUqzlLnQcVubNswZuiG4/AeF7BoObwPFsO4IPYg96 AOoCognFLLTTAqRXyun1FkOdsN3Vy2D1NaOLGabTqKqi64MQwrRXK8bvaRRUCkjPseKY 1kGDDpCiEI+IW3/AgOddICOVkYmv2I2VP7ogity0oYBePOvKWc5Ypxwqx6BX9I8NBZkW iCHBQcZNqUN/Dyrnqy65eQCwm79fl0no7rhoNpHz++y8v2JkYS7H+rOAJJEUp54xtjVm +plXGYscxW4FpoVK5nk73CWrY1XHw5wwLDnf1CA+MQOdU0t8V/dKxk8uBULwyLPJ0sNz qHcw== 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 :organization:message-id:subject:cc:to:from:date; bh=fqOknRIi8zzlQ/O6cpP54uHGMmBlBDmNaI4i4OwTa94=; b=lYDn5UKr4Sn6mgjl/gKdhw3AxNXdRu7gszSZLQ5qmWYHijXnJb8EcUhZVdF+chRkmA dGTYihofaRX/RxfVmkDW7jZiK3AllfYLN0Rx/kYebtS+BnSyjzSBE/w+sZNPTjpZIiGU 3E1fWxIoxKonw/3PG0Q+RZKiRqWYVb7FiVRO/nepzQfFh4zYc3EDtiDoyVFDbxqnvyX3 pht8GvveRm7o15Qrrzz/GvLR6+cX9jwgteiLZWj6LpoAgwH5BdDvhZUEzIXIaVRqdjmv 2VbdOdk62pcis+ACnbDq4Lnse5f5nfnVRHPjEqVwHo/fcMORiPr6gqORGf6cNGeMsHnP 5/uw== ARC-Authentication-Results: i=1; mx.google.com; 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 Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id c4si7610854pfi.110.2019.01.11.11.39.16; Fri, 11 Jan 2019 11:39:17 -0800 (PST) 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; 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 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2388680AbfAKTjQ (ORCPT + 31 others); Fri, 11 Jan 2019 14:39:16 -0500 Received: from ms.lwn.net ([45.79.88.28]:60176 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730371AbfAKTjP (ORCPT ); Fri, 11 Jan 2019 14:39:15 -0500 Received: from lwn.net (localhost [127.0.0.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id E27D22F3; Fri, 11 Jan 2019 19:39:14 +0000 (UTC) Date: Fri, 11 Jan 2019 12:39:14 -0700 From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: Mauro Carvalho Chehab , LKML Subject: [PATCH] kernel-doc: suppress 'not described' warnings for embedded struct fields Message-ID: <20190111123841.6f195c2c@lwn.net> Organization: LWN.net MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org The ability to add kerneldoc comments for fields in embedded structures is useful, but it brought along a whole bunch of warnings for fields that could not be described before. In many cases, there's little value in adding docs for these nested fields, and in cases like: struct a { struct b { int c; } d, e; }; "c" would have to be described twice (as d.c and e.c) to make the warnings go away. We can no doubt do something smarter, but simply suppressing the warnings for this case removes about 70 relatively useless warnings from the docs build, freeing us to focus on the ones that matter more. So make kerneldoc be silent about missing descriptions for any field containing a ".". Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) -- 2.20.1 diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c5333d251985..3350e498b4ce 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1474,7 +1474,7 @@ sub push_parameter($$$$) { if (!defined $parameterdescs{$param} && $param !~ /^#/) { $parameterdescs{$param} = $undescribed; - if (show_warnings($type, $declaration_name)) { + if (show_warnings($type, $declaration_name) && $param !~ /\./) { print STDERR "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n"; ++$warnings;