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.
