[PATCH 3/3] text: Add some documentation to the text protocol.

[Michael Hasselmann]

On Tue, 2012-08-21 at 18:28 +0200, Jan Arne Petersen wrote:
> From: Jan Arne Petersen <jpetersen at openismus.com>
> +    <description summary="text model">
> +      A model for text input. Adds support for text input and input methods to
> +      applications. A text_model object is created from a text_model_factory and
> +      corresponds typically to a text entry in an application. Requests are used
> +      to activate/deactivate the model and set informations like surrounding and
> +      selected text or the content type. The information about entered text is
> +      sent to the model via the preedit and commit events.
> +    </description>

I think this paragraph deserves a more high-level introduction, because
the concept we introduce here is a somewhat new approach:

Traditionally, applications (or the toolkit in use) would assume they
process hardware events directly and try to compose text from that. With
the text model, for the majority of use-cases, this should no longer be
necessary. A regular text editor should work by just using this
protocol, without direct hardware event processing.

This is also what we try to prove in the Weston example, no?

>      <request name="set_surrounding_text">
>        <arg name="text" type="string"/>
>      </request>
> @@ -7,10 +15,21 @@
>        <arg name="index" type="uint"/>
>      </request>
>      <request name="activate">
> +      <description summary="request activation">
> +        Requests the model to be activated (typically when the text entry gets
> +        focus). The seat argument is a wl_seat which maintains the focus for
> +        this activation. The surface argument is a wl_surface assigned to the
> +        model and tracked for focus lost.
> +      </description>

If it is a request, you should perhaps explain under which condition it
can get rejected. I can imagine that the compositor would deny
activation of a text model that is bound to an invisible surface.

Also mention that upon successful activation, you'll get the activated
event (but perhaps that's already so well established as a general
concept in Wayland we don't have to mention it all the time).

>        <arg name="seat" type="object" interface="wl_seat"/>
>        <arg name="surface" type="object" interface="wl_surface"/>
>      </request>
>      <request name="deactivate">
> +      <description summary="request activation">

Wrong summary.

> +    <event name="deactivated">
> +      <description summary="deactivated event">
> +        Notify the model when it is deactivated. Either in response to a
> +        deactivate request or when the assigned surface lost focus or was
> +	destroyed.
> +      </description>
> +    </event>

So when would a surface lose focus? Please list some cases.

>    </interface>
>  
>    <interface name="text_model_factory" version="1">
> +    <description summary="text model factory">
> +      A factory for text models. This object is a singleton global.
> +    </description>

Allows the compositor to keep track of issued text models, right?
Perhaps mention why we do that.

>    <interface name="input_method_context" version="1">
> +    <description summary="input method context">
> +      Corresponds to a text model on input method side. An input method context
> +      is created on text mode activation on the input method side. It allows to
> +      receive information about the text model from the application via events.
> +      Input method contexts do not keep state after deactivation and should be
> +      destroyed after deactivation is handled.
> +    </description>

Could make it a bit more visual by writing: "input_method_context
mirrors the text_model on the input method side. Requests become events
and events become requests.

> +    <description summary="input method">
> +      An input method object is responsible to compose text in repsonse to

                                                            typo --^

> +      input from hardware or virtual keyboards. There is one input method
> +      object per seat. On activate there is a new input method context object
> +      created which allows the input method to communicate with the text model.
> +    </description>