Received: by 2002:a05:6a10:6744:0:0:0:0 with SMTP id w4csp1227636pxu; Sat, 24 Oct 2020 04:35:44 -0700 (PDT) X-Google-Smtp-Source: ABdhPJwmbBKrzItb/daNMTT+dpN+QywGUTnfBcYQtR/R6CFgGCpuvZP3wXyjBgSmb2r5L9g84YwQ X-Received: by 2002:a50:f156:: with SMTP id z22mr1537612edl.94.1603539344692; Sat, 24 Oct 2020 04:35:44 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1603539344; cv=none; d=google.com; s=arc-20160816; b=DDdv98u4ikkcmRWOrM8RcuSfOO8kX5c0JjNfIDQyziHkeb053ncsrOB0KGxpEDSe/r jDOgB2daWI9Y9kn7rfxw/J0hsIgxRI+9oJhIiHX6XGUrXJwbkGi3wfv0WK/nT+fErFzF 4+fVk6a69MAqlkMkXVrQz5srr+GZts2k+yEHv3NHRf5wApVlqNqms+sgCzqQ5xVH0lsw 9s35UTbzrdglilFlCEPBUGWExttmGSYS/wUzqP49chA9TkqaYhuyJHyE7XAYGOAXeXJ0 TJ/xuLHPlDtcrfGoIGKVMVn2RMmE1/4QDEBf4S+AiRINsjed5NFix2VMjprqfL/OTTNk yMrg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:subject:cc:to:from:date :dkim-signature; bh=2Lipb9UCMrDSYoDEmJRoO9kDNopMNxHZm//aXK1SpXc=; b=GLGoq0bFmk0PlwtANYNADwYyr6OJzPPXOvoatEsNqK56gjWEqVLFpmBGvhR38C8Mvj oRJt937n0Ru7vZGwwTJD5/Es+9cxqIP7YaXkiqI3dxXwzCYAk03YBFTXROmX7Aql/iPu 7rHGVPxhq4LVqV50igKHxX6oQQ7Oc53ad/j04TtBkEQoCLNqq1Vka9MZNSAURDQHZ7j3 7od6ytzZvOitHUrgbPRUPZLsQz4309SK2IbcMWSRDMQcslPdX+uFiu4V6lKXmQpDxVXq viqS8p9mJDefxPCxJFGljDMZWuaIWVD+19tY7PkROv39M+ZInHNraRys15xdHMx9cKlK LR5w== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@kernel.org header.s=default header.b=bplk10sT; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [23.128.96.18]) by mx.google.com with ESMTP id k1si2828387edf.460.2020.10.24.04.35.22; Sat, 24 Oct 2020 04:35:44 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18; Authentication-Results: mx.google.com; dkim=pass header.i=@kernel.org header.s=default header.b=bplk10sT; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1759751AbgJXG2e (ORCPT + 99 others); Sat, 24 Oct 2020 02:28:34 -0400 Received: from mail.kernel.org ([198.145.29.99]:58818 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1759746AbgJXG2d (ORCPT ); Sat, 24 Oct 2020 02:28:33 -0400 Received: from coco.lan (ip5f5ad5d6.dynamic.kabel-deutschland.de [95.90.213.214]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 208AB2225F; Sat, 24 Oct 2020 06:28:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1603520912; bh=5v86lVR1XneVpVP+Hzz236herCmsEq7eWDuD8TBA06w=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=bplk10sTPdwHZ5QH2EJQ1zHFzguHpaHFpQUAbpHPoF71qMsRQkeZ4svdQYs2Q3pEQ hWzB3zXqsxCq/NPvA13SjvyCtuSFDy4PLBjK8hkGvvNeh0lw4Yjxozyqe8s73kqfz2 xJhXrYReVvjDdH6o+pJkALdJgd5lGKgR1qAh9FVA= Date: Sat, 24 Oct 2020 08:28:27 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet Cc: Peter Zijlstra , Kees Cook , Linux Doc Mailing List , Ard Biesheuvel , Ingo Molnar , Jann Horn , Will Deacon , linux-kernel@vger.kernel.org Subject: Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup Message-ID: <20201024082827.08ad3010@coco.lan> In-Reply-To: <20201023134757.628f91b7@lwn.net> References: <202010231039.DE05B63@keescook> <20201023193907.GI2974@worktop.programming.kicks-ass.net> <20201023134757.628f91b7@lwn.net> X-Mailer: Claws Mail 3.17.7 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Fri, 23 Oct 2020 13:47:57 -0600 Jonathan Corbet escreveu: > On Fri, 23 Oct 2020 21:39:07 +0200 > Peter Zijlstra wrote: > > > > > /** > > > > - * struct refcount_t - variant of atomic_t specialized for reference counts > > > > + * struct refcount_struct - variant of atomic_t specialized for reference counts > > > > > > Hm, this is a weird one. Yes, it's actually "struct refcount_struct", > > > but the usage should be refcount_t (through the typedef). I'm not sure > > > what the right way to document this is. > > > > Yeah, this is wrong. If this is due to a kernel doc warning, the kernel > > doc machinery is wrong *again*. This issue has nothing to do with warnings. The problem here is that "struct" is a markup for structs, and not for typedefs. > > ...except that, since refcount_t is a typedef, "struct refcount_t" doesn't > actually exist. Whether it works properly after doing s/struct// remains > to be seen... If the intent is to document the struct and its internal fields, this kernel-doc should work: /** * struct refcount_struct - variant of atomic_t specialized for reference counts * @refs: atomic_t counter field * * The counter saturates at REFCOUNT_SATURATED and will not move once * there. This avoids wrapping the counter and causing 'spurious' * use-after-free bugs. */ Which produces this result: .. c:struct:: refcount_struct variant of atomic_t specialized for reference counts **Definition** :: struct refcount_struct { atomic_t refs; }; **Members** ``refs`` atomic_t counter field (description) See, in this case, the identifier is not opaque: its members are documented at the html (or man) output. If you want, instead, to document the typedef, this is the proper way: /** * typedef refcount_t - variant of atomic_t specialized for reference counts * * The counter saturates at REFCOUNT_SATURATED and will not move once * there. This avoids wrapping the counter and causing 'spurious' * use-after-free bugs. */ It will handle this one as an opaque type, meaning that it won't be showing the "refs" field - even if you forget to drop the @refs: at the markup. The result will be: .. c:type:: refcount_t variant of atomic_t specialized for reference counts (description) - If you want both, then you would either split struct and typedef, e. g. with something like: /** * struct refcount_struct - variant of atomic_t specialized for reference counts * @refs: atomic_t counter field * * The counter saturates at REFCOUNT_SATURATED and will not move once * there. This avoids wrapping the counter and causing 'spurious' * use-after-free bugs. */ struct refcount_struct { atomic_t refs; }; /** * typedef refcount_t - variant of atomic_t specialized for reference counts * @refs: atomic_t counter field * * The counter saturates at REFCOUNT_SATURATED and will not move once * there. This avoids wrapping the counter and causing 'spurious' * use-after-free bugs. */ typedef struct refcount_struct refcount_t; Or, you could add the member at the description field. E. g. something like this: /** * typedef refcount_t - variant of atomic_t specialized for reference counts * * The counter saturates at REFCOUNT_SATURATED and will not move once * there. This avoids wrapping the counter and causing 'spurious' * use-after-free bugs. * * Members: * ``refs`` * atomic_t counter field */ typedef struct refcount_struct { atomic_t refs; } refcount_t; If you want to test it, you can run kernel-doc directly, to see how it will parse it. For ReST output, that's the syntax: ./scripts/kernel-doc --sphinx-version 3 include/linux/refcount.h Thanks, Mauro