Vladimir Sementsov-Ogievskiy <[email protected]> writes: > On 29.10.25 12:08, Markus Armbruster wrote: >> Vladimir Sementsov-Ogievskiy <[email protected]> writes: >> >>> Hi all! >>> >>> Let's bring the documentation in line with the requirements. And >>> do check these requirements in QAPI parser. >> >> Prior art: >> >> 01bed0ff14 qapi: Refill doc comments to conform to conventions >> 7270819384 qga/qapi-schema: Refill doc comments to conform to current >> conventions >> 209e64d9ed qapi: Refill doc comments to conform to current conventions >> >> These only touched prose. >> >> Your series also touches examples, is split per source file, and adds >> code to enforce the rules automatically. >> >> Automatic enforcement makes a ton of sense. Should've tried to code it >> up long ago. Much appreciated! However, it's in the first patch. It >> needs to go last to not break bisection. >> >> I don't think splitting per source file is necessary. >> >> I'd prefer to put aside examples for now and focus on prose, since the >> case for prose is much stronger. >> >> Since I already split off the prose changes for my own review purposes, >> there's no need for you to do that again. I'll take care of it. >> >> However, we need to adjust the enforcement code to skip examples. >> >> Examples are marked up with ReST directive qmp-example. They look like >> this: >> >> # .. qmp-example:: >> # >> # the example >> # text is >> # indented >> >> The stupidest solution that could possibly work is to start skipping the >> checks at >> >> # .. qmp-example:: >> >> and resume it at the first unindented line. >> >> This is of course a hack: it second-guesses the ReST parser. I think >> it's good enough. >> >> If we in a later step decide reflowing the examples is usful, the hack >> goes away. >> >> Would you be willing to take care of that part? > > Of course. Will you send a detached prose changes, so I can base changed > patch 01 on top of it?
Cool! I'll make my patches somewhat more presentable after lunch, and send you an URL to git-fetch them.
