[libvirt] [PATCH] docs: Format bit shift notation for bitwise flag enums

[Daniel P. Berrangé]

On Tue, Jan 29, 2019 at 08:41:59AM -0500, John Ferlan wrote:
> 
> 
> On 1/29/19 8:07 AM, Daniel P. Berrangé wrote:
> > On Thu, Jan 24, 2019 at 03:43:15PM +0100, Peter Krempa wrote:
> >> Big number itself does not make much sense in some cases. Format the
> >> bitshift format as well.
> >>
> >> Changes our web page docs from:
> >>
> >> VIR_MIGRATE_POSTCOPY = 32768 : Setting the VIR_MIGRATE_POSTCOPY...
> >> VIR_MIGRATE_TLS      = 65536 : Setting the VIR_MIGRATE_TLS flag...
> >>
> >> to:
> >>
> >> VIR_MIGRATE_POSTCOPY = 32768 (1<<15) : Setting the VIR_MIGRATE_POSTCOPY...
> >> VIR_MIGRATE_TLS      = 65536 (1<<16) : Setting the VIR_MIGRATE_TLS flag...
> > 
> > I tend to question why we are reporting the value in the docs at all.
> > 
> > The whole point of enums/constants is that developers should never care
> > about the actual. They should exclusively use the names.
> > 
> > So if anything I'd suggest we remove the existing numbers from the docs,
> > instead of adding the bitshift values.
> > 
> 
> I think it would look odd without some value, but I could be in the
> minority opinion on that.
> 
> As a developer sometimes you have to debug things and wonder what a
> value means. There's a few values which jump from "smaller" values to
> much larger values (e.g. VIR_CONNECT_GET_ALL_DOMAINS_STATS_NOWAIT) where
> values go from 1, 2, 4, etc. jumping up to 536870912, 1073741824, etc.
> 
> While yes, open source someone can look it up, but perhaps the first
> place to look is the docs. The visual cue of seeing (1 << 29), (1 <<
> 30), etc. would be enough for me.

Actually, yes, I was forgetting about the case of debugging where knowing
the real values is important.

For "flags" at least, the logs will typically have the values printed in
hex & you need to look them up.  So I wonder if we could usefully
print both decimal & hex in the docs (and the bit shift) ?


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|