Re: [PATCH] cleanup: Add usage and style documentation

From: Dan Williams <dan.j.williams@intel.com>
To: Matthew Wilcox <willy@infradead.org>,
	Dan Williams <dan.j.williams@intel.com>
Cc: "Peter Zijlstra" <peterz@infradead.org>,
	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 Järvinen" <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
Date: Sat, 23 Mar 2024 17:57:45 -0700	[thread overview]
Message-ID: <65ff7a88e93fb_2690d29429@dwillia2-mobl3.amr.corp.intel.com.notmuch> (raw)
In-Reply-To: <Zf8_RYHW7QmCzl2-@casper.infradead.org>

Matthew Wilcox wrote:
> On Fri, Mar 22, 2024 at 12:10:38PM -0700, Dan Williams wrote:
> > Peter Zijlstra wrote:
> > > 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.
> 
> I would rather you ignored Peter's persistent whining about RST and
> kept the formatting.

Hmm, how about split the difference and teach scripts/kernel-doc to treat
Peter's preferred markup for a C code example as a synonym, i.e.
effectively a search and replace of a line with only:

	Ex.

...with:

	.. code-block:: c

...within a kernel-doc DOC: section?

Might be easier said the done as I stare down a pile of perl. Maybe a
perl wrangler will come along and take pity on this patch.