Received-SPF: pass (google.com: domain of linux-kernel+bounces-112836-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1;
Date: Sun, 24 Mar 2024 13:37:51 -0700
From: Dan Williams <dan.j.williams@intel.com>
To: Jonathan Corbet <corbet@lwn.net>, Dan Williams <dan.j.williams@intel.com>,
	Matthew Wilcox <willy@infradead.org>
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 =?iso-8859-1?Q?J=E4rvinen?=
	<ilpo.jarvinen@linux.intel.com>, Lukas Wunner <lukas@wunner.de>,
	<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: <66008f1fddaf9_2690d294f4@dwillia2-mobl3.amr.corp.intel.com.notmuch>
References: <171097196970.1011049.9726486429680041876.stgit@dwillia2-xfh.jf.intel.com>
 <20240322090630.GA40102@noisy.programming.kicks-ass.net>
 <65fdd7ae82934_4a98a29429@dwillia2-mobl3.amr.corp.intel.com.notmuch>
 <Zf8_RYHW7QmCzl2-@casper.infradead.org>
 <65ff7a88e93fb_2690d29429@dwillia2-mobl3.amr.corp.intel.com.notmuch>
 <871q802dzt.fsf@meer.lwn.net>
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <871q802dzt.fsf@meer.lwn.net>
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?u3Y/MJLW369HkqXG/o3Xie+D+EuwlSchmPw+6PJLXnFPYNejnxTasd+2EKNZ?=
 =?us-ascii?Q?dtTRH68UL6y+1wvzL+pFk+qcsLFk+UhPMEOw7at9Wbb9556PgNE0ICo03FiA?=
 =?us-ascii?Q?upqn5Fx3ZHEeHomDB3ovNv3dHBoZv2l69mKSVVx0pzMlk7uvHSytaFiU7T2V?=
 =?us-ascii?Q?WlC3Phj2pFn+mgF28qsdifreaOBTY2SWUjiv0T5M/bqxMjcdGlhko0XQqYzJ?=
 =?us-ascii?Q?9I0PcnCkAWR8e3mQ+ONeI4QQgGmY+IZX04uuXTBIFsscBGw/SXQRrkdWe9fB?=
 =?us-ascii?Q?giRVqKhxcB6qT64gKcdixxASsKooEokv1aZCe4JxaCDB/3arU6Vz7WbhXxhD?=
 =?us-ascii?Q?/s9CLUPiUkMPqwbUtI3ijl9Z5J+pcN9GSiasXmrAAEaJU3Lel4SBb+Hi8hYJ?=
 =?us-ascii?Q?XDZI/OthXlWhnDxsRrRlW5w4LXmbhF7ymRWowpgKRF/C2mAL7guxhs8djR8l?=
 =?us-ascii?Q?Kdiu9og4KnMEYxJxoJwDBbvYv1kPAiNXUKU6OG7o/oIpAXO7YZ2vLQWDUfVP?=
 =?us-ascii?Q?5lbGdBYfbUNTvCbGZU8OzJA9iOuo+TT/i/Ff/L5Uq8GNHb9TArJA/kzROCST?=
 =?us-ascii?Q?xWgibwVs2VrLCUCLP7pQZr7mc/TMRkgLg1RdAZuQD+05rm2XVMzkIIVfFpw7?=
 =?us-ascii?Q?n5omFW1BJz0GCqP5v21dYoPRyMSCcinuXs9p4Wal1eWiLXtZS0jPcw9YCxFI?=
 =?us-ascii?Q?LHEQ2zC7PQQMGb7lKMITfCL9YCsPjrvUtY8IAxh92kdmImpd75SKV5Wf5cMe?=
 =?us-ascii?Q?hHpXMJgku6BUemiOqF50Nbe+oSMJ7V6/Ro1XLqWq1GLav5W+1EPzUCP5E3tE?=
 =?us-ascii?Q?2RqD6pX2tV18+eiC6GVs0jtNx5EwhY/Lkn2zCGAigYvBuCNInv2+v/Tnuppn?=
 =?us-ascii?Q?ZlopE86z57bb0AxHq8idYM8cIIF8Gsc8yzUj/7Z79Vjt/Kugqsm8SaEEh+LQ?=
 =?us-ascii?Q?Q6H6XpNbW3/WuQC+BAynbfMUZE/UPgtVhMxqcfOiJCHj7msSA59HeNNU2Dg7?=
 =?us-ascii?Q?zp+MisF2t8t6w8xrgooKMOZHRzX1+v5p9yPq2ENy/VQuJDB68B8ygBiaRUYw?=
 =?us-ascii?Q?J2nLbWrJLzqqi4/Bp8oJF7ooDtcyL0Q+hjOPYTPRcO2RuNka/W8cNONVgY8B?=
 =?us-ascii?Q?SS/domoc9m6WXW2rUmqQ4UF2EIulRDEN1DWzTkN6WAazPhbjrYYkhvzLe/WO?=
 =?us-ascii?Q?VSwSZ4f/sbvyLW0vKNiBA8LUkGpdDJH7nMqEOm+/83m0VujZLxKdnGlY6lgR?=
 =?us-ascii?Q?dSKrScUFQGsY06x08GUtQlxRMBfJ5ZUp4Ap3PNTVniPC59LeOsXW7no4d8Xy?=
 =?us-ascii?Q?0M2s3nPTIY+RagRauhxZKwmBTsdXWyobthTEK6o809KBO5AObD973rZyIt3x?=
 =?us-ascii?Q?BNxGWmHnbdRho5Vj/BQ7FZUVy+w7qlgUqcn0Tl0psVPKs4LsKawOnnqRNW+s?=
 =?us-ascii?Q?K2ep5aN0gV76AEpCfsSx11pxXDOwLyUd9shNwNFqjRbpeA5oV1+rCJ1uR/gr?=
 =?us-ascii?Q?2T9E3T0tp2hcFk4Z4H2iROfI+nNJkcqy545chnSdpHcbrgPFmA1OYM8YEFOo?=
 =?us-ascii?Q?ujLnEHIXnskUmH0giquezuXKZMQbnXnwZ8t0C1TQrDPIQ7la6PMNQAMvk8Zh?=
 =?us-ascii?Q?8A=3D=3D?=
X-MS-Exchange-CrossTenant-Network-Message-Id: 41eb31f6-6317-478b-f54d-08dc4c424887
X-MS-Exchange-CrossTenant-AuthSource: SA3PR11MB8118.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 24 Mar 2024 20:37:54.9451
 (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: wDcGF39CN2i4S7zZ4OEp1A4GSjf9MazkhnrUL5YHpkre3Q2RedFzag7b1DaLLb+mnb+p6BT/yytGFykJFu+J838a95Hjsl0blVVDuUvnvKg=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: MW4PR11MB6786
X-OriginatorOrg: intel.com

Jonathan Corbet wrote:
> Dan Williams <dan.j.williams@intel.com> writes:
> 
> > 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.
> 
> Dealing with that is definitely the least pleasant part of trying to
> maintain docs...

What is Linux development if not a surprising ongoing discovery of one-off
local preferences?

FWIW, I think the ability to embed RST markup directly into source code
documentation is a slick mechanism. It is something I welcome into any
file I maintain. At the same time, for files I do not maintain,
maintainer deference indicates "jettison some markup syntax to move the
bigger picture forward".

> > 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?
> 
> I'm not convinced that "Ex." is a clearer or more readable syntax, and
> I'd prefer to avoid adding to the regex hell that kernel-doc already is
> or adding more special syntax of our own.  How about, as Lukas
> suggested, just using the "::" notation?  You get a nice literal block,
> albeit without the syntax highlighting -- a worthwhile tradeoff, IMO.

Sounds reasonable to me, will do that for v2.

Lukas, thanks for the help!