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

[Nils Chr. Brause]

Okay.

Reviewed-by <nilschrbrause at googlemail.com>


On Wed, Oct 21, 2015 at 3:34 PM, Auke Booij <auke at tulcod.com> wrote:
> 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.