Memos From the Cube

I’ve got another MyUSB API conundrum for the library users to indicate their preference about.

When I first started the project, I gave all the descriptor elements custom names which I thought were more insightful than their USB 2.0 counterparts. That was fine for me, but I’m a little worried that it might cause confusion amongst MyUSB users using the 2.0 specification for reference. Sure, the elements are in the same order as the specification and are reasonably easy to match up with the specification, but I want to put it to the users to decide what is used in the final 1.5.0 release.

There are six options that I can think of:

1) Keep everything as it is. Parameter names stay the same, as do the custom descriptor element names. Leave it up to the user (or explicitly state in the documentation) to match up the elements with their USB 2.0 Specification counterparts.

2) Replace the descriptor and function parameter names with the official USB 2.0 specification names. Would require all projects to update function prototypes and descriptors.

3) Use a union and anonymous structures (an extension of AVR-GCC) to allow both the MyUSB and the official names to be used in the descriptors (meaning that Somedescriptor.MyUSBName and Somedescriptor.officialName would both be accepted and would both refer to the same item) but keep the custom parameter names for compatibility. Would not require any changes to existing projects, but may induce confusion if part of an app uses the MyUSB names, and another uses the official names.

4) Same as the above but change the function parameter names to the USB 2.0 counterparts, forcing applications to update their function prototypes but not their descriptors. Would be the most painful option.

5) Go with option 2 if a special USB_USESPECIFICATIONNAMES or similar token is defined, otherwise default to the current MyUSB names.

6) Opposite to 5, use official names unless USB_USEOLDNAMES is defined.

Well, how about it? If I don’t get too many opinions on this I’ll just assume the majority is content with things the way they are and go with option 1.