Received-SPF: pass (google.com: domain of linux-kernel+bounces-111979-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
Date: Fri, 22 Mar 2024 12:10:38 -0700
From: Dan Williams <dan.j.williams@intel.com>
To: Peter Zijlstra <peterz@infradead.org>, Dan Williams
	<dan.j.williams@intel.com>
CC: <torvalds@linux-foundation.org>, Bjorn Helgaas <bhelgaas@google.com>, "Ira
 Weiny" <ira.weiny@intel.com>, Jonathan Cameron <jonathan.cameron@huawei.com>,
	Jesse Brandeburg <jesse.brandeburg@intel.com>, Ilpo
 =?iso-8859-1?Q?J=E4rvinen?= <ilpo.jarvinen@linux.intel.com>, Lukas Wunner
	<lukas.wunner@intel.com>, Jonathan Corbet <corbet@lwn.net>,
	<linux-pci@vger.kernel.org>, <linux-kernel@vger.kernel.org>,
	<gregkh@linuxfoundation.org>, <linux-doc@vger.kernel.org>
Subject: Re: [PATCH] cleanup: Add usage and style documentation
Message-ID: <65fdd7ae82934_4a98a29429@dwillia2-mobl3.amr.corp.intel.com.notmuch>
References: <171097196970.1011049.9726486429680041876.stgit@dwillia2-xfh.jf.intel.com>
 <20240322090630.GA40102@noisy.programming.kicks-ass.net>
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <20240322090630.GA40102@noisy.programming.kicks-ass.net>
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?RIWC4LgefcY/dI/JwvYqZ5SuC0FQoxuLBjakrduQp5TnniPYPR7XsQmtIF28?=
 =?us-ascii?Q?CwdGYUCt1FXffuNQxE57mXKawgiNIpCCRqxf6eyFl515yAPZdDagE/txNFb6?=
 =?us-ascii?Q?crei75uqB+PBeB8fDK1gAe1VNA4sV5VJfBOPs3uTalYxgKuS0tAE3bYxHdXs?=
 =?us-ascii?Q?NrOigkcULORAnhxIsJIGw57tW9+C1/5UeXt8ZvLb62YyyJ3MNA8tM34pC6mT?=
 =?us-ascii?Q?l017ZtUWGEht20WlGLdu8LSiEtUk9K02hm4Iq3Njzt95ffJkdo/1XIQlOYFq?=
 =?us-ascii?Q?CuVdwgfZze17sot+OnzO8fWeBDsdLC4+qMXgQz6XJRxpKvJSAKztwoCdoLPA?=
 =?us-ascii?Q?PnOwNTRrEOudk7RyzJoTXhBUVp+8SkcZmzVDq9Hsv2sjLrGUFW23ZlepnKzl?=
 =?us-ascii?Q?eAP8zkrsJ2rqnPTMWh26BiimBhnSFVkj6cNGPVlINdoqVuVYIrSnFu0RtW89?=
 =?us-ascii?Q?vLbFrBeILGhBdLjx5U6hjqfqeaF9edv6QrrWWm6gXwoJmYF4GLOUMGA01ieG?=
 =?us-ascii?Q?FGLPxxxBX3idZDPIgbj1kgiWAemyF35Mq4uIXQ7+0wHLfCXeUYa+FpSS66HP?=
 =?us-ascii?Q?GpUFSKrZHATOHZrz/saLXoF1zg0exzo748I61jkRXc+8/fiKxFIf7j2q1mj0?=
 =?us-ascii?Q?wEDKmY2EBlBqCb0jaIZRBTZ7GjCCJDxRgxG+4a/+fAMB7q3QzM5RPoek3xmi?=
 =?us-ascii?Q?a9bYCyqskphimJbRxYBKqhSFB4a5WifEyCRf/B79hL4l7jhcc+vckmFbXNga?=
 =?us-ascii?Q?QQ5FdGN5ojg4O9kqa/HvS3p9fRv86k+9LFv9KM01jxopQuDxcmvO5GSnWNUP?=
 =?us-ascii?Q?Tvh1ej0OfGunzuiYOoi/RqJVtxfYWjwqaX7zL1EYUh2G6NJV/xQV4x13495e?=
 =?us-ascii?Q?K8KHr2rYh13hMibcNll+9+HIJayfQ6SYVrOQ6Ewe6mLHqQxabYiECBIW4SdQ?=
 =?us-ascii?Q?EwZGRlf5FFyh6or2YioxKBHw79emnBBXhqtU+/31WkW6IGwIh4TirPv4aoek?=
 =?us-ascii?Q?oa7qGq8FN7IxwuDDJCvRvDZD1qul2kMY+00KDxxTXw1+ENSbaZJxrXH24p6o?=
 =?us-ascii?Q?+E25IhEmMWLp9iTE8mCwpL8bWX71dtLJOBZiWLN8NcWaXk/Bk3OD/N1yxYcV?=
 =?us-ascii?Q?WE7aL2njJ2CzmYdssPUfQ32kMZlV/Dw92Ygk3zCTHDolVfVIKTxPIOlfzm8v?=
 =?us-ascii?Q?zLN5LiUCj7XXJRdBtw9JyXl6X5FxfPnuo1Qb0lA/JifCTggv/ksGfq1o6v7N?=
 =?us-ascii?Q?dNgZh3Ix1FAzpjbyG7GgApjhftBm9X0jegVELLAGrE9PZwTsSSVt/LfNUhJY?=
 =?us-ascii?Q?ZJiBxxCle6Wi0GmuzzcWQF9dNTFqElxyMcEQ90yaH2AsxM4o2kMjshfPqqDk?=
 =?us-ascii?Q?sWkr9kyEyqCMHNE8X2EPmMVhHntUYuP6ZR/AGsuF4ryQlqJZ6y2cmNOz/ZAb?=
 =?us-ascii?Q?yILrAMZw6zjB99voiA1qkx7CFpQ32OlOD3EAgSdAvrv7vcrzCNYNLgy07Hvo?=
 =?us-ascii?Q?5eAnBjeY0XHGOi7Ej0VJg6nyn9DraCMVSAP4a5YbDLOkTIBk+PxSEZrydNiA?=
 =?us-ascii?Q?vulJo+e049ypKXZvCsscMLFGTM3vcTYpK04aEpgVnhflqRNzHdB9knkdKkIX?=
 =?us-ascii?Q?5Q=3D=3D?=
X-MS-Exchange-CrossTenant-Network-Message-Id: 918a4db6-027a-44b1-dad2-08dc4aa3c42a
X-MS-Exchange-CrossTenant-AuthSource: PH8PR11MB8107.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 22 Mar 2024 19:10:41.2942
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: fFtJ2zf7PsFsrn5J0XN75koC5VupBLfDyAk5iCVKmjIzw6a1YfQ5NppWtTik0iTlDrbMyeXuSBkZ+0dO7E8H4o47bYuKtYVvryX1iLYwEaE=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BL3PR11MB6433
X-OriginatorOrg: intel.com

Peter Zijlstra wrote:
> On Wed, Mar 20, 2024 at 03:04:41PM -0700, Dan Williams wrote:
> 
> > diff --git a/include/linux/cleanup.h b/include/linux/cleanup.h
> > index c2d09bc4f976..4620a475faee 100644
> > --- a/include/linux/cleanup.h
> > +++ b/include/linux/cleanup.h
> > @@ -4,6 +4,118 @@
> >  
> >  #include <linux/compiler.h>
> >  
> > +/**
> > + * DOC: scope-based cleanup helpers
> > + *
> > + * The "goto error" pattern is notorious for introducing subtle resource
> > + * leaks. It is tedious and error prone to add new resource acquisition
> > + * constraints into code paths that already have several unwind
> > + * conditions. The "cleanup" helpers enable the compiler to help with
> > + * this tedium and can aid in maintaining FILO (first in last out)
> > + * unwind ordering to avoid unintentional leaks.
> > + *
> > + * As drivers make up the majority of the kernel code base lets describe
> > + * the Theory of Operation, Coding Style implications, and motivation
> > + * for using these helpers through the example of cleaning up PCI
> > + * drivers with DEFINE_FREE() and DEFINE_GUARD(), e.g.:
> > + *
> > + * .. code-block:: c
> > + *
> 
> So I despise all that RST stuff. It makes what should be trivially
> readable text into a trainwreck. We're coders, we use text editors to
> read comments.

Ok, I will rip out the RST stuff and just make this a standalone comment.