[PATCH] doc: Added API documentation for wl_display_destroy and wl_display_add_socket functions.

[Srivardhan]

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 at lists.freedesktop.org]
> On Behalf Of Bryce Harrington
> Sent: Monday, October 13, 2014 11:45 PM
> To: Srivardhan Hebbar
> Cc: wayland-devel at 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 at 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 at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel