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

[John Ferlan]

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.

John