From patchwork Wed Nov 2 11:48:01 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Akira Yokosawa X-Patchwork-Id: 14195 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:6687:0:0:0:0:0 with SMTP id l7csp3569627wru; Wed, 2 Nov 2022 04:51:38 -0700 (PDT) X-Google-Smtp-Source: AMsMyM5B/OFlPbIH/2raVQqF6T6662Zf5x0NF5qDYRW6TyRH6F3AsjeY/z3pQGZzsY+eWRC8vKuz X-Received: by 2002:a05:6402:50d4:b0:461:e349:56b2 with SMTP id h20-20020a05640250d400b00461e34956b2mr24613589edb.17.1667389898471; Wed, 02 Nov 2022 04:51:38 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1667389898; cv=none; d=google.com; s=arc-20160816; b=dmOx8napgXMHOxI/ubtr5dMjEVzWxNXOd6M0Qkfz3u624CqBOpMwXn46g6EugLlFBo 0ubUiedwHEHINnmyvdK0g/KLP+5V4yzjwEAtlLVpxdl0UuqtdVXhjuI4cRDevD/JDRrS VaCDc+rFEC1j1sSCBL6DLUxZdUw+S3i0CwArEOS+/YhTBqU9lzhfLpOb3C1mp4inUQgf VyjR6EHrvrprSVrbzc77xqwxztaGzjZquMeajL0zylKtN7YheVarzQlVLEH8RS/oihUb j93sG3rzLzcEGnax1OYzjZVu/CKcs19GnvB/zfIuI5frcuExHDmmjtp2qV+2nPVM/w4b AKsA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:content-language:cc:to :subject:from:user-agent:mime-version:date:message-id:dkim-signature; bh=lrt48o0wxQzQSNwn9v0lTmEHxq/zDXHhMvj06dfThtY=; b=nGd8W45S27peFCXYyLkRWGHdv20AUB2s0AMpvIQy6vNWNVuJVlsZsJftm6A92e6nep uQGfd0ImLz/kL65UePw/HZ50mmtvvGogeD8OQs4bSmZItf4y8vqmuZIp/vrOv1WG4iHN XunF+ctHzdi33CdH4juDJ/SIgg/R9GBCMs3GwPMtEQyqQpOZse0xcY9fzptTGgDfhiOR U8PjfsRT1cBV12Cyq9+hvnXe94H1zBKUI68wkTncWCFNWX3+vVbH5J6f227Pal8jr6MC qwI9vrysFyBFEQHEcAbO7pct+OcbsWZLUaKcECiv9E9dZQ3LgzZBmz/qBR36stWZHTo3 3osw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gmail.com header.s=20210112 header.b=TY2LrmuI; 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: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id du1-20020a17090772c100b0078dcddc1b8csi14636368ejc.788.2022.11.02.04.51.14; Wed, 02 Nov 2022 04:51:38 -0700 (PDT) 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=TY2LrmuI; 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 S230303AbiKBLsP (ORCPT + 99 others); Wed, 2 Nov 2022 07:48:15 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45404 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230298AbiKBLsK (ORCPT ); Wed, 2 Nov 2022 07:48:10 -0400 Received: from mail-pl1-x631.google.com (mail-pl1-x631.google.com [IPv6:2607:f8b0:4864:20::631]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 510C228723; Wed, 2 Nov 2022 04:48:07 -0700 (PDT) Received: by mail-pl1-x631.google.com with SMTP id j12so16330381plj.5; Wed, 02 Nov 2022 04:48:07 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:content-language:cc:to:subject:from :user-agent:mime-version:date:message-id:from:to:cc:subject:date :message-id:reply-to; bh=lrt48o0wxQzQSNwn9v0lTmEHxq/zDXHhMvj06dfThtY=; b=TY2LrmuIAoR+xdiGyBablBuIPoXvzxK6cMCmSG4gN3TWjqpd30TwaP+LzPRqMH1drI +y/3lRjhS9NFfbNfUjgujDC5BH2NgR733/m96E7Oe4xYVN0ym+ftOuQKxbgaRke+rS6Z Wp8r+sgub3NlWrpc/YSJBmmikuvfmKyqmXAfpmmKgFtXYQRJagntlifh68AauVxlB1BF /AEeCt4+brNpUwI+Lb8j47PnhjsA/I+rvCuYnbhmFFhk6eEdUUyKjT2Ib6WrNtaapS5U rU99ywZWfG7MKxJdg5hWcAKdNZSHE5x7Gph/KiaVXz1I8g5OMdi4zmVPKP1U7qf9/cNs ozaA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:content-language:cc:to:subject:from :user-agent:mime-version:date:message-id:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to; bh=lrt48o0wxQzQSNwn9v0lTmEHxq/zDXHhMvj06dfThtY=; b=tKSbla9CumoMIV0Py4EjrTGWj245m8MALqX6d7GtCs9qbSm/451Rw17RnCmGndQ+en +JckLjt67wZqggJhnQvaOcCcJ1kCWKhfs0MR8TtC9UqX2Q7DAmEQzKY7jq4McgeC0c+K nJis1XT/ZV4X+/ohn9IMUpGPBF8qG962eJpP7ZXuyc6bcEWh9B7f5zDxJy3T2ZVlmdTa XBLwhxwCVOoPPj38fcSmquqv1HsIkPhlUhV0ikCug2F2fQZzzY3us3bA8/PhDXCjNPva +/+EAyt+k46PzYr+eSZ4m23rfDStuwgWKgu+uDFZFr0LtEiN+LH9nhxi1tVBBUtGAx/l tFxw== X-Gm-Message-State: ACrzQf3VutA3WgvbXj6k/8j5Mpu/dNpR96tNmOitFzJLMGZv0GJahxm2 12fMlEwC/KRhhLGxqSsFcDQ= X-Received: by 2002:a17:90b:4f45:b0:213:ccc6:87df with SMTP id pj5-20020a17090b4f4500b00213ccc687dfmr19537471pjb.227.1667389686843; Wed, 02 Nov 2022 04:48:06 -0700 (PDT) Received: from [192.168.11.9] (KD106167171201.ppp-bb.dion.ne.jp. [106.167.171.201]) by smtp.gmail.com with ESMTPSA id 13-20020a62190d000000b00562cfc80864sm8295435pfz.36.2022.11.02.04.48.04 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 02 Nov 2022 04:48:06 -0700 (PDT) Message-ID: <4e54c76a-138a-07e0-985a-dd83cb622208@gmail.com> Date: Wed, 2 Nov 2022 20:48:01 +0900 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.2.2 From: Akira Yokosawa Subject: [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c To: Jiri Slaby , Greg Kroah-Hartman , Jonathan Corbet Cc: Akira Yokosawa , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Content-Language: en-US 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, 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 X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1748385030277658594?= X-GMAIL-MSGID: =?utf-8?q?1748385030277658594?= 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 Reviewed-by: Jiri Slaby --- 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. Thanks, Akira -- Documentation/driver-api/miscellaneous.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) base-commit: 30a0b95b1335e12efef89dd78518ed3e4a71a763 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) ============================