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

[Bryce Harrington]

On Wed, Oct 21, 2015 at 02:34:48PM +0100, Auke Booij 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.

Good to hear.

I think we can reasonably expect any reasonably knowledgeable software
engineer will know the simple definition for bitfields and enums, to
having our document describe them in a bit more erudite specificity is
probably ok.

> >>
> >>        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.

Seems a reasonable, conservative approach.

(IMHO signed data types are used far too often.  Can you imagine how many
bugs might have been prevented over the years if instead of int being
signed by default, it was unsigned by default, and you'd have to declare
"signed int" to get negative numbers.)

Bryce