the daily dub

March 15th, 2010

Failure to Communicate

Posted by rdub in Rants
tagged: | |

The transparent_union type attribute enables you to specify atransparent_union type, that is, a union data type qualified with__attribute__((transparent_union))__.

This is an actual example of some real documentation from ARM’s RealView Compiler Toolkit – used to build high-performance ARM binaries.

What this roughly translates to is this:

A transparent_union type is a type with a transparent_union attribute.

Well, no shit, Sherlock!  What the fuck does the attribute do to the type or the handling thereof?

To contrast, here’s what GCC’s manual says in the first sentence:

This attribute, attached to a union type definition, indicates that any function parameter having that union type causes calls to that function to be treated in a special way.

This is somewhat better – with one sentence of (not wasted space), I already know that the transparent_union attribute has something to do with function parameters, and, additionally, causes some special handling thereof.

That said, I’m still not clear (in one sentence) what this attribute does, but GCC is certainly off to a better start.

ARM, work on your documentation please.

submit to reddit