[PATCH wayland 1/1] doc: Formalize file comment in wayland-client.h, wayland-server.h

[Bryce Harrington]

On Tue, May 10, 2016 at 06:05:44PM -0700, Bryce Harrington wrote:
> On Sun, May 08, 2016 at 02:42:28PM -0500, Yong Bakos wrote:
> > From: Yong Bakos <ybakos at humanoriented.com>
> > 
> > Publican was generating a subtle error during a build:
> > Error: no ID for constraint linkend: Server-wayland-server-core_8h.
> > 
> > This was caused by doxygen applying the doc comment at the top of
> > wayland-server.h as the documentation for struct wl_object. As such, the
> > generated documentation for wl_object was also very incorrect.
> > 
> > Make the file doc comments in wayland-client.h and wayland-server.h real
> > doxygen file doc comments with the \file command, add a \brief, make the
> > inclusion warning a \warning, correct the language of the comment in
> > wayland-server.h, and remove one unnecessary line break.
> > 
> > This squelches the publican error, removes the bad wl_object documentation,
> > and makes the comment appear in the generated html documentation.
> > 
> > References: d74a9c079b1aeb44f69b4132dc2c38362e21f281
> > 
> > Signed-off-by: Yong Bakos <ybakos at humanoriented.com>
> 
> LGTM,
> 
> Reviewed-by: Bryce Harrington <bryce at osg.samsung.com>

Thanks, pushed:
   c6d204f..e5b12aa  master -> master

 
> > ---
> >  src/wayland-client.h | 7 +++++--
> >  src/wayland-server.h | 9 ++++++---
> >  2 files changed, 11 insertions(+), 5 deletions(-)
> > 
> > diff --git a/src/wayland-client.h b/src/wayland-client.h
> > index 3856535..9f70fa3 100644
> > --- a/src/wayland-client.h
> > +++ b/src/wayland-client.h
> > @@ -23,8 +23,11 @@
> >   * SOFTWARE.
> >   */
> >  
> > -
> > -/** Use of this header file is discouraged. Prefer including
> > +/** \file
> > + *
> > + *  \brief Include the client API and protocol C API.
> > + *
> > + *  \warning Use of this header file is discouraged. Prefer including
> >   *  wayland-client-core.h instead, which does not include the
> >   *  client protocol header and as such only defines the library
> >   *  API.
> > diff --git a/src/wayland-server.h b/src/wayland-server.h
> > index b6d0e2b..3124703 100644
> > --- a/src/wayland-server.h
> > +++ b/src/wayland-server.h
> > @@ -23,10 +23,13 @@
> >   * SOFTWARE.
> >   */
> >  
> > -
> > -/** Use of this header file is discouraged. Prefer including
> > +/** \file
> > + *
> > + *  \brief Include the server API, deprecations and protocol C API.
> > + *
> > + *  \warning Use of this header file is discouraged. Prefer including
> >   *  wayland-server-core.h instead, which does not include the
> > - *  client protocol header and as such only defines the library
> > + *  server protocol header and as such only defines the library
> >   *  API, excluding the deprecated API below.
> >   */
> >  
> > -- 
> > 2.7.2
> > 
> > _______________________________________________
> > wayland-devel mailing list
> > wayland-devel at lists.freedesktop.org
> > https://lists.freedesktop.org/mailman/listinfo/wayland-devel
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel