doc: Added API documentation for wl_display_destroy and wl_display_add_socket functions.

Submitted by Srivardhan Hebbar on Oct. 13, 2014, 11:54 a.m.

Details

Message ID 1413201255-1452-1-git-send-email-sri.hebbar@samsung.com
State Superseded
Headers show

Not browsing as part of any series.

Commit Message

Srivardhan Hebbar Oct. 13, 2014, 11:54 a.m.
Signed-off-by: Srivardhan Hebbar <sri.hebbar@samsung.com>
---
 src/wayland-server.c | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

Patch hide | download patch | download mbox

diff --git a/src/wayland-server.c b/src/wayland-server.c
index 674aeca..0f61e6e 100644
--- a/src/wayland-server.c
+++ b/src/wayland-server.c
@@ -862,6 +862,15 @@  wl_socket_alloc(void)
 	return s;
 }
 
+/** Destroy Wayland display object.
+ *
+ * \param display The Wayland display object which should be destroyed.
+ * \return None.
+ *
+ * This destroys the wl_display object which has been passed.
+ *
+ * \memberof wl_display
+ */
 WL_EXPORT void
 wl_display_destroy(struct wl_display *display)
 {
@@ -1181,6 +1190,17 @@  wl_display_add_socket_auto(struct wl_display *display)
 	return NULL;
 }
 
+/** Add a socket to Wayland display for the clients to connect.
+ *
+ * \param display Wayland display to which the socket should be added.
+ * \param name Name of the Unix socket.
+ * \return 0 if success. -1 if failed.
+ *
+ * This adds a Unix socket to Wayland display which can be used by clients to
+ * connect to Wayland display.
+ *
+ * \memberof wl_display
+ */
 WL_EXPORT int
 wl_display_add_socket(struct wl_display *display, const char *name)
 {

Comments

On Mon, Oct 13, 2014 at 05:24:15PM +0530, Srivardhan Hebbar wrote:
> Signed-off-by: Srivardhan Hebbar <sri.hebbar@samsung.com>
> ---
>  src/wayland-server.c | 20 ++++++++++++++++++++
>  1 file changed, 20 insertions(+)
> 
> diff --git a/src/wayland-server.c b/src/wayland-server.c
> index 674aeca..0f61e6e 100644
> --- a/src/wayland-server.c
> +++ b/src/wayland-server.c
> @@ -862,6 +862,15 @@ wl_socket_alloc(void)
>  	return s;
>  }
>  
> +/** Destroy Wayland display object.
> + *
> + * \param display The Wayland display object which should be destroyed.
> + * \return None.
> + *
> + * This destroys the wl_display object which has been passed.

I think the reader could guess this from the function name.  ;-)

Might be more informative to mention that it frees the object itself,
along with freeing all contained sockets and globals, and releases any
additional shm formats.

> + * \memberof wl_display
> + */
>  WL_EXPORT void
>  wl_display_destroy(struct wl_display *display)
>  {
> @@ -1181,6 +1190,17 @@ wl_display_add_socket_auto(struct wl_display *display)
>  	return NULL;
>  }
>  
> +/** Add a socket to Wayland display for the clients to connect.
> + *
> + * \param display Wayland display to which the socket should be added.
> + * \param name Name of the Unix socket.
> + * \return 0 if success. -1 if failed.
> + *
> + * This adds a Unix socket to Wayland display which can be used by clients to
> + * connect to Wayland display.

Again, we should try to avoid adding documentation which merely restates
the function name, and try to say something meaningful.

There are three different ways the routine can fail, all of which return
-1; these three situations would be worth mentioning.

The routine attempts to use the WAYLAND_DISPLAY environment variable,
and if that's not set it assumes "wayland-0".  This behavior would also
be worth mentioning in the documentation.

Thanks for giving attention to the code documentation; this can be
invaluable to future end users.

Bryce
Thanks for the comments... :) 
I will incorporate the comments and send the V2 of the patch soon.

Thank-you,
Hebbar

> -----Original Message-----
> From: wayland-devel [mailto:wayland-devel-bounces@lists.freedesktop.org]
> On Behalf Of Bryce Harrington
> Sent: Monday, October 13, 2014 11:45 PM
> To: Srivardhan Hebbar
> Cc: wayland-devel@lists.freedesktop.org
> Subject: Re: [PATCH] doc: Added API documentation for wl_display_destroy
> and wl_display_add_socket functions.
> 
> On Mon, Oct 13, 2014 at 05:24:15PM +0530, Srivardhan Hebbar wrote:
> > Signed-off-by: Srivardhan Hebbar <sri.hebbar@samsung.com>
> > ---
> >  src/wayland-server.c | 20 ++++++++++++++++++++
> >  1 file changed, 20 insertions(+)
> >
> > diff --git a/src/wayland-server.c b/src/wayland-server.c
> > index 674aeca..0f61e6e 100644
> > --- a/src/wayland-server.c
> > +++ b/src/wayland-server.c
> > @@ -862,6 +862,15 @@ wl_socket_alloc(void)
> >  	return s;
> >  }
> >
> > +/** Destroy Wayland display object.
> > + *
> > + * \param display The Wayland display object which should be destroyed.
> > + * \return None.
> > + *
> > + * This destroys the wl_display object which has been passed.
> 
> I think the reader could guess this from the function name.  ;-)
> 
> Might be more informative to mention that it frees the object itself,
> along with freeing all contained sockets and globals, and releases any
> additional shm formats.
> 
> > + * \memberof wl_display
> > + */
> >  WL_EXPORT void
> >  wl_display_destroy(struct wl_display *display)
> >  {
> > @@ -1181,6 +1190,17 @@ wl_display_add_socket_auto(struct wl_display
> *display)
> >  	return NULL;
> >  }
> >
> > +/** Add a socket to Wayland display for the clients to connect.
> > + *
> > + * \param display Wayland display to which the socket should be added.
> > + * \param name Name of the Unix socket.
> > + * \return 0 if success. -1 if failed.
> > + *
> > + * This adds a Unix socket to Wayland display which can be used by
clients
> to
> > + * connect to Wayland display.
> 
> Again, we should try to avoid adding documentation which merely restates
> the function name, and try to say something meaningful.
> 
> There are three different ways the routine can fail, all of which return
> -1; these three situations would be worth mentioning.
> 
> The routine attempts to use the WAYLAND_DISPLAY environment variable,
> and if that's not set it assumes "wayland-0".  This behavior would also
> be worth mentioning in the documentation.
> 
> Thanks for giving attention to the code documentation; this can be
> invaluable to future end users.
> 
> Bryce
> _______________________________________________
> wayland-devel mailing list
> wayland-devel@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel