[PATCH weston 05/15] libweston: two more weston_output docs

[Pekka Paalanen]

On Tue, 4 Apr 2017 21:48:05 +0200
Armin Krezović <krezovic.armin at gmail.com> wrote:

> On 04.04.2017 12:58, Pekka Paalanen wrote:
> > From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> > 
> > Document two more functions of the weston_output API.
> > 
> > Exported functions marked internal are meant for backends only.
> > Exported functions not marked internal are meant for libweston users.
> > 
> > Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>  
> 
> I'm not familiar with (guessing) doxygen notations, but wording and spelling
> seem in order. Documentation is always welcome, thank you. Again, same question
> about live -> enabled in this patch, too.
> 
> Nevertheless,
> 
> Reviewed-by: Armin Krezović <krezovic.armin at gmail.com>

Hi Armin,

the doxygen notation is not even too used yet, but the markings and
their logic (backend API vs. public API) is readable without doxygen as
well. "Live" fixed again.


Thanks,
pq

> 
> Thanks, Armin.
> 
> > ---
> >  libweston/compositor.c | 40 ++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 40 insertions(+)
> > 
> > diff --git a/libweston/compositor.c b/libweston/compositor.c
> > index 09a3db2..69e63c2 100644
> > --- a/libweston/compositor.c
> > +++ b/libweston/compositor.c
> > @@ -4466,6 +4466,8 @@ weston_output_move(struct weston_output *output, int x, int y)
> >   *
> >   * \param compositor The compositor instance.
> >   * \param output The output to be added.
> > + *
> > + * \internal
> >   */
> >  WL_EXPORT void
> >  weston_compositor_add_output(struct weston_compositor *compositor,
> > @@ -4482,6 +4484,20 @@ weston_compositor_add_output(struct weston_compositor *compositor,
> >  		weston_view_geometry_dirty(view);
> >  }
> >  
> > +/** Transform device coordinates into global coordinates
> > + *
> > + * \param device_x[in] X coordinate in device units.
> > + * \param device_y[in] Y coordinate in device units.
> > + * \param x[out] X coordinate in the global space.
> > + * \param y[out] Y coordinate in the global space.
> > + *
> > + * Transforms coordinates from the device coordinate space
> > + * (physical pixel units) to the global coordinate space (logical pixel units).
> > + * This takes into account output transform and scale.
> > + *
> > + * \memberof weston_output
> > + * \internal
> > + */
> >  WL_EXPORT void
> >  weston_output_transform_coordinate(struct weston_output *output,
> >  				   double device_x, double device_y,
> > @@ -4543,6 +4559,9 @@ weston_output_enable_undo(struct weston_output *output)
> >   * are made inert.
> >   *
> >   * - The output is put back in the pending outputs list.
> > + *
> > + * \memberof weston_output
> > + * \internal
> >   */
> >  static void
> >  weston_compositor_remove_output(struct weston_output *output)
> > @@ -4580,6 +4599,8 @@ weston_compositor_remove_output(struct weston_output *output)
> >   *
> >   * It only supports setting scale for an output that
> >   * is not enabled and it can only be ran once.
> > + *
> > + * \memberof weston_output
> >   */
> >  WL_EXPORT void
> >  weston_output_set_scale(struct weston_output *output,
> > @@ -4605,6 +4626,8 @@ weston_output_set_scale(struct weston_output *output,
> >   * Refer to wl_output::transform section located at
> >   * https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_output
> >   * for list of values that can be passed to this function.
> > + *
> > + * \memberof weston_output
> >   */
> >  WL_EXPORT void
> >  weston_output_set_transform(struct weston_output *output,
> > @@ -4627,6 +4650,9 @@ weston_output_set_transform(struct weston_output *output,
> >   *
> >   * Sets initial values for fields that are expected to be
> >   * configured either by compositors or backends.
> > + *
> > + * \memberof weston_output
> > + * \internal
> >   */
> >  WL_EXPORT void
> >  weston_output_init(struct weston_output *output,
> > @@ -4661,6 +4687,9 @@ weston_output_init(struct weston_output *output,
> >   * configuration.
> >   *
> >   * The opposite of this operation is built into weston_output_destroy().
> > + *
> > + * \memberof weston_output
> > + * \internal
> >   */
> >  WL_EXPORT void
> >  weston_compositor_add_pending_output(struct weston_output *output,
> > @@ -4835,6 +4864,17 @@ weston_pending_output_coldplug(struct weston_compositor *compositor)
> >  		wl_signal_emit(&compositor->output_pending_signal, output);
> >  }
> >  
> > +/** Uninitialize an output
> > + *
> > + * Removes the output from the live outputs list if necessary, but
> > + * does not call the backend's output disable function.
> > + *
> > + * All fields of weston_output become uninitialized, i.e. should not be used
> > + * anymore. The caller can free the memory after this.
> > + *
> > + * \memberof weston_output
> > + * \internal
> > + */
> >  WL_EXPORT void
> >  weston_output_destroy(struct weston_output *output)
> >  {
> >   
> 
> 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20170724/b15bc3ea/attachment-0001.sig>