John Snow <[email protected]> writes: > On Wed, Sep 16, 2026 at 5:38 AM Markus Armbruster <[email protected]> wrote: >> >> John Snow <[email protected]> writes: >> >> > This patch converts some slightly-non-trivial intros with more than >> > one paragraph, but doesn't create any new intro/details splits. >> > >> > Review notes: Some of these possibly could be split, but as they are >> > commands >> > (not eligible as an inlining source) and the additional information in >> > the intro is not terribly long, I opted to leave them alone instead of >> > laboring on prose rewrites. >> > >> > Signed-off-by: John Snow <[email protected]> >> > --- >> > qapi/block-core.json | 49 +++++++++++++++++++++----------------------- >> > qapi/block.json | 29 +++++++++++++------------- >> > qapi/migration.json | 9 ++++---- >> > qapi/misc-arm.json | 9 ++++---- >> > qapi/misc.json | 13 ++++++------ >> > qapi/qdev.json | 14 ++++++------- >> > 6 files changed, 58 insertions(+), 65 deletions(-) >> > >> > diff --git a/qapi/block-core.json b/qapi/block-core.json >> > index 1ca147285e7..c505369aeb2 100644 >> > --- a/qapi/block-core.json >> > +++ b/qapi/block-core.json >> > @@ -1772,13 +1772,12 @@ >> > >> > ## >> > # @blockdev-snapshot: >> > +# Takes a snapshot of a block device. >> > # >> > -# Takes a snapshot of a block device. >> > -# >> > -# Take a snapshot, by installing 'node' as the backing image of >> > -# 'overlay'. Additionally, if 'node' is associated with a block >> > -# device, the block device changes to using 'overlay' as its new >> > -# active image. >> > +# Take a snapshot, by installing 'node' as the backing image of >> > +# 'overlay'. Additionally, if 'node' is associated with a block >> > +# device, the block device changes to using 'overlay' as its new >> > +# active image. >> >> 'overlay' and 'node' refer to arguments, so they should be @overlay and >> @node. Since the arguments are in type BlockdevSnapshot, the reference >> is non-local until the inliner lands. > > It isn't a reference at all as far as Sphinx is concerned, merely a > markup convention. Whether or not that convention applies to non-local > things is kind of up to you. If you say the word, I'll edit these in > this series and forward if you wish, but my default will be to leave > it alone.
Right now, improving markup is a distraction we need to avoid. We should still take notes for later, though. The obvious goal is to mark up references to things so they can be suitably rendered, preferably as links. Solved markup problem for references to definitions (`name-of-defn`) and local member descriptions (@name-of-member). We don't have a good solution for referencing non-local member descriptions. >> We may want to render this paragraph below the argument descriptions to >> avoid forward references. This requires splitting it off the intro. We >> can do it now, or leave it for later. >> >> Not splitting now keeps the conversion simple, which is a plus. It >> reindents the entire unsplit intro, and if we do split it later, the >> part split off gets reindented right back. >> >> I'm leaning towards not rocking the boat, but you decide. > > I'm likely to forget or ignore about later splits, so if it's > something you want, we may as well do it now. Note that we can just > decide to only indent the first paragraph and leave the second > unindented, and then it gets shifted into place during a later code > movement patch. Yes, that's splitting off the intro. It forces us to revisit the doc comment when we eliminate the plain sections between intro and tagged sections. Simple way to punt contents work down the road some. I'm encouraging you to do that when you're less than sure the contents should be intro, simply because the primary goal right now is to get the syntax conversion done. Limiting followup cleanup work is secondary: we do it whenever it doesn't distract us from the primary. Makes sense? >> Not noting these things again. >> >> > # >> > # Features: >> > # >> > @@ -2471,15 +2470,15 @@ >> > ## >> > # @block-dirty-bitmap-merge: >> > # >> >> Drop the blank line. > > ACK. Accidental remnants of adding a blank line intentionally to get > reflow to behave how I want. > >> >> > -# Merge dirty bitmaps listed in @bitmaps to the @target dirty bitmap. >> > -# Dirty bitmaps in @bitmaps will be unchanged, except if it also >> > -# appears as the @target bitmap. Any bits already set in @target will >> > -# still be set after the merge, i.e., this operation does not clear >> > -# the target. On error, @target is unchanged. >> > +# Merge dirty bitmaps listed in @bitmaps to the @target dirty >> > +# bitmap. Dirty bitmaps in @bitmaps will be unchanged, except if >> > +# it also appears as the @target bitmap. Any bits already set in >> > +# @target will still be set after the merge, i.e., this operation >> > +# does not clear the target. On error, @target is unchanged. >> > # >> > -# The resulting bitmap will count as dirty any clusters that were >> > -# dirty in any of the source bitmaps. This can be used to achieve >> > -# backup checkpoints, or in simpler usages, to copy bitmaps. >> > +# The resulting bitmap will count as dirty any clusters that were >> > +# dirty in any of the source bitmaps. This can be used to achieve >> > +# backup checkpoints, or in simpler usages, to copy bitmaps. >> > # >> > # Errors: >> > # - If @node is not a valid block device, DeviceNotFound >> > @@ -5848,15 +5847,14 @@ >> > >> > ## >> > # @block-set-write-threshold: >> > +# Change the write threshold for a block drive. An event will be >> > +# delivered if a write to this block drive crosses the configured >> > +# threshold. The threshold is an offset, thus must be >> > +# non-negative. Default is no write threshold. Setting the >> > +# threshold to zero disables it. >> > # >> > -# Change the write threshold for a block drive. An event will be >> > -# delivered if a write to this block drive crosses the configured >> > -# threshold. The threshold is an offset, thus must be non-negative. >> > -# Default is no write threshold. Setting the threshold to zero >> > -# disables it. >> > -# >> > -# This is useful to transparently resize thin-provisioned drives >> > -# without the guest OS noticing. >> > +# This is useful to transparently resize thin-provisioned drives >> > +# without the guest OS noticing. >> > # >> > # @node-name: graph node name on which the threshold must be set. >> > # >> > @@ -5938,11 +5936,10 @@ >> > >> > ## >> > # @x-blockdev-set-iothread: >> > +# Move @node and its children into the @iothread. If @iothread is >> > +# null then move @node and its children into the main loop. >> > # >> > -# Move @node and its children into the @iothread. If @iothread is >> > -# null then move @node and its children into the main loop. >> > -# >> > -# The node must not be attached to a BlockBackend. >> > +# The node must not be attached to a BlockBackend. >> >> This one arguably lacks an intro. Let's not worry about this now. > > How about I indent *nothing* and lead with a "#TODO: This command > needs an introduction" ? Do we want every command to have an intro? If we do, we should enforce it at some point. If we plan to enforce it, simply leaving the intro empty now will be caught without a TODO. I'm taking note: 9. Consider making intro mandatory (maybe just for commands and events?) >> > # >> > # @node-name: the name of the block driver node >> > # >> > diff --git a/qapi/block.json b/qapi/block.json >> > index e47592d5500..15f08372564 100644 >> > --- a/qapi/block.json >> > +++ b/qapi/block.json >> > @@ -181,12 +181,13 @@ >> > >> > ## >> > # @blockdev-close-tray: >> > +# Closes a block device's tray. >> > # >> > -# Closes a block device's tray. If there is a block driver state tree >> > -# associated with the block device (which is currently ejected), that >> > -# tree will be loaded as the medium. >> > +# If there is a block driver state tree associated with the block >> > +# device (which is currently ejected), that tree will be loaded as >> > +# the medium. >> > # >> > -# If the tray was already closed before, this will be a no-op. >> > +# If the tray was already closed before, this will be a no-op. >> > # >> > # @device: Block device name >> > # >> >> Shouldn't this one be in "[PATCH 5/9] qapi: split intro sections for >> commands"? > > Ah, I did something halfway between ... Well, this particular block > doesn't actually add a new "split", but I did reflow the paragraphs > *as if* I had performed the split. You're right. > Let's collapse this one way or the other: please state your > preference, and I'll sift it into the correct patch. Breaking the paragraph like you did feels like an improvement to me. If we think the contents after the paragraph split should not be intro, then the adjusted patch should be in "[PATCH 5/9] qapi: split intro sections for commands". If we think keeping it in intro is fine, then it should stay here. However, the paragraph split is an unnecesseary contents improvement then. Better to keep the syntax conversion patches focused to ease review. I'm leaning towards the latter. Thus: ## # @blockdev-close-tray: -# -# Closes a block device's tray. If there is a block driver state tree -# associated with the block device (which is currently ejected), that -# tree will be loaded as the medium. -# -# If the tray was already closed before, this will be a no-op. +# Closes a block device's tray. If there is a block driver state +# tree associated with the block device (which is currently +# ejected), that tree will be loaded as the medium. +# +# If the tray was already closed before, this will be a no-op. # # @device: Block device name # Thoughts? [...]
