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 :| -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
