[PATCH v2 1/4] doc: document the enum and bitfield attributes

[Auke Booij]

On 21 October 2015 at 13:13, Nils Chr. Brause <nilschrbrause at gmail.com> wrote:
> Hi,
>
> On Tue, Oct 20, 2015 at 9:38 AM, Bryce Harrington <bryce at osg.samsung.com> wrote:
>> On Tue, Oct 20, 2015 at 12:01:14AM -0700, Bryce Harrington wrote:
>>> On Mon, Oct 19, 2015 at 11:21:23PM +0100, Auke Booij wrote:
>>> > Introduce the enum and bitfield attributes, which allow you to refer to the enum
>>> > you are expecting in an argument, and specify which enums are to be thought of
>>> > as bitfields.
>>> >
>>> > +      Additionally, the protocol can specify <type>enum</type>s.  These are used
>>> > +      to list options for <type>int</type> and <type>uint</type> type arguments.
>>> > +      Arguments can refer to the specific enumeration that is semantically
>>> > +      implied.  Only in the case that the argument is of type <type>uint</type>,
>>> > +      it can be specified that the primary interface to its numeric value deals
>>> > +      with bitwise operations, for example when arbitrarily many choices of the
>>> > +      enum can be ORed together.
>>> > +    </para>
>>> > +    <para>
>>> > +      The purpose of the <type>enum</type> and <type>bitfield</type> attributes
>>> > +      is to document what arguments refer to which enums, and to document which
>>> > +      numeric enum values are primarily accessed using bitwise operations.
>>> > +      Additionally, the enum and bitfield attributes may be used by other code,
>>> > +      such as bindings to other languages, for example to enhance type safety of
>>> > +      code.  However, such usage is only supported if the following property is
>>> > +      satisfied: code written prior to the specification of these attributes
>>> > +      still works after their specification.  In other words, specifying an
>>> > +      attribute for an argument, that previously did not have an enum or
>>> > +      bitfield attribute, should not break API.  Code that does not satisfy this
>>> > +      rule is not guaranteed to obey backwards compatibility.
>>>
>>> This next chunk gets a bit too jarringly technical too quickly.  I think
>>> your second paragraph gives a better intro to these attributes, but it
>>> doesn't work to simply swap them.  Let me take a shot at copyediting
>>> this a bit:
>>>
>>> I think this is clearer, and hopefully hasn't lost any meaning.  I'm not
>>> sure it's improved the technicality of this prose...  perhaps this
>>> section would be better promoted to its own section, with maybe just a
>>> reference sentence included here?  Not sure.
>>
>> I'm noticing now that I've misunderstood what the bitfield attribute is;
>> so the above text is incorrect.  Let me try again.
>>
>>        Additionally, the protocol can specify <type>enum</type>s which
>>        associate specific numeric enumeration values.  These are
>>        primarily just description in nature: at the wire format level
>>        enums are just integers.  But they also serve a secondary purpose
>>        to enhance type safety or otherwise add context for use in
>>        language bindings or other such code.  This latter usage is only
>>        supported so long as code written before these attributes were
>>        introduced still works after; in other words, adding an enum
>>        should not break API, otherwise it puts backwards compatibility
>>        at risk.
>>
>>        <type>enum</type>s can be defined as bitfields or just a set of
>>        integers.  This is specified via the <type>bitfield</type>
>>        boolean attribute in the <type>enum</type> definition.  If this
>>        attribute is true, the enum is intended to be accessed primarily
>>        using bitwise operations, for example when arbitrarily many
>>        choices of the enum can be ORed together; if it is false, or the
>>        attribute is omitted, then the enum arguments are a just a
>>        sequence of numerical values.
>
> I  am fine with that wording, but it actually is much simpler than that:
> In a bitfield every bit has a distinct meaning. In an enumeration, that
> is not the case. :)

Like any suggestion us foreign language binders make, while yours is
perfectly reasonable in principle, C's abuse of everything makes me
want to be a bit careful in this. Additionally, after a long
discussion, this is the kind of wording that people seemed to agree
on, so personally, I am not planning to make drastic changes in this
again.

I think Bryce's suggestion will not cause any further disagreements,
so I will probably use that in an updated patch.

>
>>
>>        The <type>enum</type> attribute can be used on either
>>        <type>uint</type> or <type>int</type> arguments, however if the
>>        <type>enum</type> is defined as a <type>bitfield</type>, it can
>>        only be used on <type>uint</type> args.
>
> Just out of curiosity: Why does the signess matter for a bitfield?

The signedness matters because the signedness shouldn't matter. And if
it really doesn't matter, we might as well require it to be unsigned:
this is the typical type of a bit field in C, and a signed int
suggests something else is going on. I'm intentionally careful here:
in my imagined use case, bit fields are unsigned. A signed bit field
is something I don't know, and don't make any promises about.

If signed bit fields later turn out to be a thing that we want, we can
always start allowing that in a later stage. The reverse is not true:
we cannot stop allowing signed bit fields.

That's why.