I'm writing a library which includes some wrapper code for some underlying API. In that underlying API, there are two concepts, "foo" and "bar", whose literal meaning in the English dictionary is close to the switching of their meaning in the API. i.e. it uses "foo" for something that's close to "bar" and vice-versa.
(For the curious: It's basically "thread index" vs "thread id" in CUDA. Which one do you suppose is 3-dimensional and which is a linearization of the other?)
Now, in my wrapper code, should I...
- Stick with their incorrect and confusing terminology?
- Switch it back, explaining profusely in comments when I'm doing that?
- Go for other terms, which won't get people mixed-up, but introduce more "concept clutter"?
I'm not asking for input based on your experience with my specific case, but rather with similar situations you may have faced. Also, both a recommendation and unexpected considerations would be useful.
Note: The wrapper code does not wrap all of the underlying API, so that you only ever go through my code. So it is quite possible users will encounter the mis-named terms in other contexts. On the other hand... uses of my wrappers are always through a namespace i.e. quux::foo or quux::bar.