From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id DA50AC43217 for ; Thu, 10 Nov 2022 14:49:20 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230463AbiKJOtT (ORCPT ); Thu, 10 Nov 2022 09:49:19 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:39432 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230137AbiKJOtS (ORCPT ); Thu, 10 Nov 2022 09:49:18 -0500 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0856E17063; Thu, 10 Nov 2022 06:49:16 -0800 (PST) Received: from localhost (unknown [IPv6:2601:281:8300:73::5f6]) (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 1DF6B732; Thu, 10 Nov 2022 14:49:15 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 1DF6B732 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1668091755; bh=OnvK+2tUvYAfL0KCrr72dtwv0xTn5bAGv19wZNYmwMU=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=f+dcELpnMaM1I4cy5d4quAPLBjCS/LGb+m7YcVxJ6Z39qJd41+owPjkcNC3fnzh+0 2cVitnOOfzPKSqEzvOo8aJptjL4/EwAfILChx9pe2CeyyS7um7qnkYijGs6By4hsy3 JRvNdmD3FXnAmMqbW4YW6otpVoSTjRJOGidR25+yyypyVOzlnKP/h0/lFRRPPUB4j+ XTy7Yse+CL3yzh9nxnqHsoC/ooZbTZf/ifnGaRuVNSYQbcWeaXSQOh+dM4UfrttnxT h3iWuKUsFl3UT0CI3U5dx4ffobEydI44ecNfpm3/bxGQi8nqR9b04rIizVN2dFkMpv 8BmSo3l60hlPg== From: Jonathan Corbet To: Bagas Sanjaya , Jason Gunthorpe Cc: bpf@vger.kernel.org, David Woodhouse , iommu@lists.linux.dev, Joerg Roedel , Kevin Tian , linux-doc@vger.kernel.org, linux-kselftest@vger.kernel.org, llvm@lists.linux.dev, Nathan Chancellor , Nick Desaulniers , Miguel Ojeda , Robin Murphy , Shuah Khan , Suravee Suthikulpanit , Tom Rix , Will Deacon , Alex Williamson , Lu Baolu , Chaitanya Kulkarni , Cornelia Huck , Daniel Jordan , David Gibson , Eric Auger , Eric Farman , Jason Wang , Jean-Philippe Brucker , Joao Martins , kvm@vger.kernel.org, Matthew Rosato , "Michael S. Tsirkin" , Nicolin Chen , Niklas Schnelle , Shameerali Kolothum Thodi , Yi Liu , Keqian Zhu Subject: Re: [PATCH v4 04/17] iommufd: Document overview of iommufd In-Reply-To: References: <0-v4-0de2f6c78ed0+9d1-iommufd_jgg@nvidia.com> <4-v4-0de2f6c78ed0+9d1-iommufd_jgg@nvidia.com> Date: Thu, 10 Nov 2022 07:49:14 -0700 Message-ID: <87v8nmhnkl.fsf@meer.lwn.net> MIME-Version: 1.0 Content-Type: text/plain Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org Bagas Sanjaya writes: > On Mon, Nov 07, 2022 at 08:48:57PM -0400, Jason Gunthorpe wrote: >> From: Kevin Tian >> >> Add iommufd into the documentation tree, and supply initial documentation. >> Much of this is linked from code comments by kdoc. >> > > The patch also exposes htmldocs warnings as Stephen Rothwell has > reported on linux-next [1] due to the copyright comments mistaken for > kernel-doc comments, so I have applied the fixup: > > ---- >8 ---- > > diff --git a/drivers/iommu/iommufd/device.c b/drivers/iommu/iommufd/device.c > index 536a34d099968d..76b3761a89423e 100644 > --- a/drivers/iommu/iommufd/device.c > +++ b/drivers/iommu/iommufd/device.c > @@ -1,5 +1,6 @@ > // SPDX-License-Identifier: GPL-2.0-only > -/* Copyright (c) 2021-2022, NVIDIA CORPORATION & AFFILIATES > +/* > + * Copyright (c) 2021-2022, NVIDIA CORPORATION & AFFILIATES Um ... this makes no sense at all. If kernel-doc thought that was a kernel-doc comment, the problem is there, not here. So the report you're referring to is https://lore.kernel.org/linux-next/20221110182938.40ce2651@canb.auug.org.au/ ? If so, this change will not fix the problem. That error: > drivers/iommu/iommufd/device.c:1: warning: no structured comments found > drivers/iommu/iommufd/main.c:1: warning: no structured comments found is caused by using .. kernel-doc:: directives to extract documentation from files where none exists - thus "no structured comments found". The *real* problem, methinks, is that the directives are added in patch 4 of the series, but the documentation doesn't show up until later. So the real fix would be to simply move this patch down. Or just not worry about it, since it all works out in the end and nobody will be bisecting a docs build. Bagas, you are *again* misadvising people. Please stop doing that! Thanks, jon