Model use of Boolean values instead of enumerations

[rleigh]

The following attributes use Boolean values:

Pixels: BigEndian?, Interleaved
Objective: Iris
Laser: Tuneable, PockelCell?
Shape: Locked, Visible

From the modelling point of view, there is nothing wrong with Boolean values for these attributes. These do describe things perfectly well. However, from the generated API point of view, this is suboptimal. The problem is that true/false as method arguments and return values are not self-describing, and the code is not readable or self documenting. For example, consider this use of BigEndian? and Interleaved:

writer.setPixelType(UINT16, true, false);

and compare with the use of enums:

writer.setPixelType(UINT16, BIG_ENDIAN, CHUNKY)

where BIG_ENDIAN is one of the endianness enumerations, and CHUNKY is one of the interleaving enumerations.

This means that it's impossible to accidentally swap the arguments since they are specific enums where the boolean options were interchangeable. And it also means they can be used with C++ templates and Java generics as type-specific template parameters.

Suggestions for enums:

BigEndian?: change name to Endian with Big and Little enumerations [also allows for Mixed]
Interleaved: change name to Interleaving with Chunky and Planar enumerations
Iris: Add Absent and Present enumerations [more specific iris enumerations are possible]
PockelCell?: Add Absent and Present enumerations [more specific enumerations are possible]
Tuneable: change name to Tuning with None and Tunable enumerations [more specific SingleLine?, MultiLine?, NarrowBand? etc. enumerations could also be added]
Visible: change name to Visibility with Visible and Invisible enumerations
Locked: change name to Modifiable with Locked and Unlocked enumerations

Better naming is obviously possible, these are just initial suggestions.

The main points are to

• make the API safer
• make the code more readable
• allow use in templates
• allow extension of the "true" cases with finer-grained options, i.e. allowing for future extensibility

[rleigh]

​https://github.com/rleigh-dundee/bioformats/compare/spec-enums?expand=1 contains the changes to convert each boolean value to an enum, one commit per enum (also attached here). These contain everything except the upgrade transforms. We might not want to convert all of these; each commit can be applied in isolation to select specific enums. The only ones I really care about for my C++ work are the Endian and SubChannelInterleaving? enums.

One question which came up discussing this with Chris was the need for BigEndian? on BinData? given that it's already present on Pixels. What actually needs this attribute? The only other user is Mask, and without a corresponding pixel type/word size, it's not clear what BigEndian? even means in this context. Is it actually needed, or could it be moved completely over to Pixels and removed entirely from BinData??

[jamoore]

We'll soon be going through bug clean-up. I'm removing "Bug:" from this since it's more of a RFE. Might be this needs a representation on trello as well.