Received: by 2002:a05:6358:d09b:b0:dc:cd0c:909e with SMTP id jc27csp624249rwb; Wed, 9 Nov 2022 06:54:08 -0800 (PST) X-Google-Smtp-Source: AMsMyM5X9KVViIBXmH7QlKSi4peYPKhsOAYgvxewmQdVCO0UAz25EFGjCAJpHYqTvkRLxUErZrxR X-Received: by 2002:a65:408b:0:b0:42a:55fb:60b0 with SMTP id t11-20020a65408b000000b0042a55fb60b0mr52578117pgp.431.1668005647997; Wed, 09 Nov 2022 06:54:07 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1668005647; cv=none; d=google.com; s=arc-20160816; b=Y1LSZAkHsnntjTe2uBPnsrw9CWNmvD8FGZj1bk9kQyY9Gl5DCp9CILQHYafa2go+mH BL815nnC6QseZCon4qkI0QHcWdJ2nTk0xx9mVSt+6QhhWi8m0vK6aJM5PCSXuaQgAgyw G/UcRF0j5I4x5RZmcxDdYLZkXpqIWYWckbLbGVGui82Zs2XDqS3q99OSoSif6bSK8ckx usBmw28WORdUWFm18Q6AayoJjJGzjw54K6/UiO358kBj4druvQjKij+ir7HLBgCnlQo7 uGYN8vrH367oYerJ7fEvjnAw5Oz3sbDvwS6Cj2L0USlz1QUb8zigv7oRgty/t6jlsU0w XRqg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:in-reply-to:from :references:cc:to:content-language:subject:user-agent:mime-version :date:message-id:dkim-signature; bh=EykLsHeIVHRO9PdnUtJ+KSnyFBk98kvT0QI6KNtiYAM=; b=XO5HeAX84URqlwpTduDW7qU60eFy0oRv6W5m3uetN1n5rVDSz3clFnmDLUReFL+Qg5 rvHIqmdtl+ghIHtA9NQReDpD47TGBTvrUewoV0BYnXlnTIf2WLgqF0lajWc/IT3T9MWj TDCa6jDC1jug+78p2dLQSrN298YGjoZfQPZqrilcNyiXAF64BV1JSdttx8V5D7yLqjtl XGazgbls39WpGFrZRoJ5UtnilZuacpWez+WmXhF3VwVWQvviCKNb36fHS4Bs/3pCiHva SiH+eAt/i1UYOlSEhlGDRTVOwT/2dHHBjcrgEudL9QDe416JntFn9i0hzo7PkE2UfrVZ vEaQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gmail.com header.s=20210112 header.b="KY2/9r6g"; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Return-Path: Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id e5-20020a17090ac20500b00214064c6c55si1371507pjt.50.2022.11.09.06.53.55; Wed, 09 Nov 2022 06:54:07 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20210112 header.b="KY2/9r6g"; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231652AbiKIOpN (ORCPT + 93 others); Wed, 9 Nov 2022 09:45:13 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:55152 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231648AbiKIOpM (ORCPT ); Wed, 9 Nov 2022 09:45:12 -0500 Received: from mail-pj1-x102a.google.com (mail-pj1-x102a.google.com [IPv6:2607:f8b0:4864:20::102a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id DB454186EB; Wed, 9 Nov 2022 06:45:10 -0800 (PST) Received: by mail-pj1-x102a.google.com with SMTP id l22-20020a17090a3f1600b00212fbbcfb78so2035504pjc.3; Wed, 09 Nov 2022 06:45:10 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:in-reply-to:from:references:cc:to :content-language:subject:user-agent:mime-version:date:message-id :from:to:cc:subject:date:message-id:reply-to; bh=EykLsHeIVHRO9PdnUtJ+KSnyFBk98kvT0QI6KNtiYAM=; b=KY2/9r6gj3wAKeO3IF1EWjaba52UxmHK7IyTetfWSTQ0g/GquJI1io9+dDzeqEX2d0 /Jg91Hb9l6hMY5QwO1WrIYZ/0kB4p5v8NWfCk45jdGZ4xsLw9QGl5wkCL7KGhIygT6P5 dJx5RDofgTF9Hs581wMo4Tdp4WorRLiOV0IPKb3YVJKnWKwRhXrZuAV6gOifD6+HyYzp E1d0bGFnr6rfZlGqH+rf3Oy6AhITS5cnOMN8Wrn4yujAvrhK/frV+M1t8FPhaqUKN9Ly DphomHbeFAenzmq2L8gwWEUpvJqSq8Tv4DCW1Aadj6dhOF0isLt1gBFBy5mhLhHLm8LZ f9Ng== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:in-reply-to:from:references:cc:to :content-language:subject:user-agent:mime-version:date:message-id :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=EykLsHeIVHRO9PdnUtJ+KSnyFBk98kvT0QI6KNtiYAM=; b=sF4wJweDvX126OiLs1pnIpJ622HSBAiwW71UMu7JQw3KSPt1SZMdwOeLbkWTe3m1kd 07ZQkvakoZc4dfjJDvU2ui+Fow2TwYcl042GhlD/fTMQtG6wA5nMfxMj3GgW6MxFr3D7 gNHJ/3vJT8Ohjb3Fs8SYE6VIw7iburEfl8eHP3Yg3i7uyS+uC5x4dNTUXVbI4fu2seaJ TAVUgQvcNq3rdrWZoTd++mESaEdwifUDFqCFnc4VvzIUsB0BDyT4lU7otFcrXIFVvt6v qCeGbYmEz4Y2g3dBHxChfR0xi3lwjlWyAkChrgUFvuTLxWpTTA+94LEXQB8Us5C6c54P n/1w== X-Gm-Message-State: ACrzQf186FOPX8cYPP1rAX3dikw3MfdIWRp6A7ys1LHnxzEDSZ9xm/6R Z+4TvOoEjpBK211TqiEeEwA= X-Received: by 2002:a17:90a:d084:b0:213:8cf1:4d34 with SMTP id k4-20020a17090ad08400b002138cf14d34mr64036139pju.150.1668005110411; Wed, 09 Nov 2022 06:45:10 -0800 (PST) Received: from [192.168.11.9] (KD106167171201.ppp-bb.dion.ne.jp. [106.167.171.201]) by smtp.gmail.com with ESMTPSA id w15-20020a1709026f0f00b001870533c443sm9149511plk.236.2022.11.09.06.45.08 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 09 Nov 2022 06:45:09 -0800 (PST) Message-ID: <47514c0a-7d5b-5a0b-6bb5-d5c96d163838@gmail.com> Date: Wed, 9 Nov 2022 23:45:06 +0900 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.2.2 Subject: Re: [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c Content-Language: en-US To: Jonathan Corbet Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Jiri Slaby , Greg Kroah-Hartman References: <4e54c76a-138a-07e0-985a-dd83cb622208@gmail.com> From: Akira Yokosawa In-Reply-To: <4e54c76a-138a-07e0-985a-dd83cb622208@gmail.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,NICE_REPLY_A, RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Hi Jon, On Wed, 2 Nov 2022 20:48:01 +0900, Akira Yokosawa wrote: > Since merge of tty-6.0-rc1, "make htmldocs" with Sphinx >=3.1 emits > a bunch of warnings indicating duplicate kernel-doc comments from > drivers/tty/serial/serial_core.c. > > This is due to the kernel-doc directive for serial_core.c in > serial/drivers.rst added in the merge. It conflicts with an existing > kernel-doc directive in miscellaneous.rst. > > Remove the latter directive and resolve the duplicates. > > Signed-off-by: Akira Yokosawa > Fixes: 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty") > Cc: stable@vger.kernel.org # 6.0 > Cc: Jiri Slaby > Cc: Greg Kroah-Hartman > --- > Hi Jiri, > > I've seeing the increased warnings of duplicates from "make htmldocs" > since the 6.0 merge window. They look like (partial): > > /linux/Documentation/driver-api/serial/driver.rst:111: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:111. > Declaration is '.. c:function:: void uart_write_wakeup(struct uart_port *port)'. > /linux/Documentation/driver-api/serial/driver.rst:111: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:111. > Declaration is '.. c:None:: struct uart_port *port'. > /linux/Documentation/driver-api/serial/driver.rst:343: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:343. > Declaration is '.. c:function:: void uart_update_timeout(struct uart_port *port, unsigned int cflag, unsigned int baud)'. > /linux/Documentation/driver-api/serial/driver.rst:343: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:343. > Declaration is '.. c:None:: struct uart_port *port'. > /linux/Documentation/driver-api/serial/driver.rst:343: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:343. > Declaration is '.. c:None:: unsigned int cflag'. > /linux/Documentation/driver-api/serial/driver.rst:343: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:343. > Declaration is '.. c:None:: unsigned int baud'. > /linux/Documentation/driver-api/serial/driver.rst:376: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:376. > > These warning messages are not easy to track down, as there is an > unresolved issue in Sphinx's C domain parser who can't handle a > function and a struct of the same name and causes duplicates in a > later stage of Sphinx processing. > > But the warnings shown above turned out to be true duplicates. > > There is a not-clearly-documented rule in including kernel-doc > comments into .rst files. Any kernel-doc comment can be included > at most once in the whole documentation tree. Otherwise, you can't > be sure of which target a cross-reference points to. > > As I don't have full context of these kernel-doc comments, this is > meant as a band-aide patch, especially the reference to > serial/driver.rst added at the bottom. > > If I can get acks from you and/or Greg, I'd like Jon to take the > fix, as this issue affects the -doc tree most. Jon, Greg has added this to his tty tree and (hopefully) it will soon land Linus' tree (v6.1-rcX). I'll ask you a back-merge once it happens. Thanks, Akira > > Thanks, > Akira > > -- > Documentation/driver-api/miscellaneous.rst | 5 ++--- > 1 file changed, 2 insertions(+), 3 deletions(-) > > diff --git a/Documentation/driver-api/miscellaneous.rst b/Documentation/driver-api/miscellaneous.rst > index 304ffb146cf9..4a5104a368ac 100644 > --- a/Documentation/driver-api/miscellaneous.rst > +++ b/Documentation/driver-api/miscellaneous.rst > @@ -16,12 +16,11 @@ Parallel Port Devices > 16x50 UART Driver > ================= > > -.. kernel-doc:: drivers/tty/serial/serial_core.c > - :export: > - > .. kernel-doc:: drivers/tty/serial/8250/8250_core.c > :export: > > +See serial/driver.rst for related APIs. > + > Pulse-Width Modulation (PWM) > ============================ > > > base-commit: 30a0b95b1335e12efef89dd78518ed3e4a71a763