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.
>
> Signed-off-by: Auke Booij <a...@tulcod.com>
> ---
> doc/publican/sources/Protocol.xml | 35 +++++++++++++++++++++++++++++------
> 1 file changed, 29 insertions(+), 6 deletions(-)
>
> diff --git a/doc/publican/sources/Protocol.xml
> b/doc/publican/sources/Protocol.xml
> index 477063b..c6178b7 100644
> --- a/doc/publican/sources/Protocol.xml
> +++ b/doc/publican/sources/Protocol.xml
> @@ -15,6 +15,32 @@
> identifies which method in the interface to invoke.
> </para>
> <para>
> + The protocol is message-based. A message sent by a client to the
> server
> + is called request. A message from the server to a client is called
> event.
> + A message has a number of arguments, each of which has a certain type
> (see
> + <xref linkend="sect-Protocol-Wire-Format"/> for a list of argument
> types).
The above is a very good addition to the document, and helps make it
more coherent in this early section by better defining requests
vs. events.
> + 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:
Additionally, the protocol can specify <type>enum</type>s and
<type>bitfield</type>s. Both of these are primarily just
descriptive in nature: at the wire format level arguments of this
type are actually just integer data, but they identify arguments
that have specific numeric enumeration values or that are intended
to be accessed primarily using bitwise operations. In addition, a
secondary purpose of the <type>enum</type> and
<type>bitfield</type> attributes is 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 or bitfield should not break API,
otherwise it puts backwards compatibility at risk.
The <type>enum</type> attribute is applicable both for
<type>int</type> and <type>uint</type> data. Arguments can refer
to the specific enumeration that is semantically implied.
<type>bitfield</type>s are only allowed for <type>uint</type>s.
This specifies 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.
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.
> + </para>
> + <para>
> The server sends back events to the client, each event is emitted from
> an object. Events can be error conditions. The event includes the
> object ID and the event opcode, from which the client can determine
> @@ -62,14 +88,11 @@
> The protocol is sent over a UNIX domain stream socket, where the
> endpoint
> usually is named <systemitem class="service">wayland-0</systemitem>
> (although it can be changed via <emphasis>WAYLAND_DISPLAY</emphasis>
> - in the environment). The protocol is message-based. A
> - message sent by a client to the server is called request. A message
> - from the server to a client is called event. Every message is
> - structured as 32-bit words, values are represented in the host's
> - byte-order.
> + in the environment).
> </para>
> <para>
> - The message header has 2 words in it:
> + Every message is structured as 32-bit words, values are represented in
> the
> + host's byte-order. The message header has 2 words in it:
The comma after "32-bit words" probably should be a semi-colon here.
Bryce
> <itemizedlist>
> <listitem>
> <para>
> --
> 2.6.1
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
_______________________________________________
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
