On Mon, 16 Dec 2019 at 16:53, Andrew Jones <drjo...@redhat.com> wrote: > > On Mon, Dec 16, 2019 at 03:06:57PM +0000, Peter Maydell wrote: > > This phrasing reads a bit confusingly to me. What I would usually expect > > is that you get > > name-of-option Description of what the option does. > > > > But here we have > > name-of-option Long description of the default behaviour, > > taking many lines and several sentences. > > Brief note at the end that enabling this > > feature gives the opposite effect. > > > > Especially since the default-behaviour description isn't prefaced > > with "By default" or similar, it's quite easy to start reading the > > text assuming it's defining what the option is going to do, only > > to get to the end and realise that it's defining what the option > > is *not* going to do... > > I'll take another stab at this, but my feeling is that a '-no-' option > should be one that just turns off the default behavior, which is why I > wrote a long description of the default behavior. If you'd prefer the > description to be more terse, then I can certainly delete a bunch of > the text, but then I fear what this option disables wouldn't be clear > enough.
I'm happy with the length of it; it would definitely be helped a lot just with phrasing that was clearer up front about that it was starting by describing the default behaviour. thanks -- PMM
