Dan Williams <dan.j.williams@xxxxxxxxx> 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... > 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. Thanks, jon
