mirrors/wayland
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland.git synced 2025-10-31 22:25:25 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: Formalize file comment in wayland-client.h, wayland-server.h

Browse source 
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: d74a9c079b

Signed-off-by: Yong Bakos <ybakos@humanoriented.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
This commit is contained in:
Yong Bakos 2016-05-08 14:42:28 -05:00 • committed by Bryce Harrington
parent c6d204fdbc
commit e5b12aa827
2 changed files with 11 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

7
src/wayland-client.h
View file

@ -23,8 +23,11 @@
* SOFTWARE. * SOFTWARE.
*/ */
/** \file
/** Use of this header file is discouraged. Prefer including *
* \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 * wayland-client-core.h instead, which does not include the
* client protocol header and as such only defines the library * client protocol header and as such only defines the library
* API. * API.

9
src/wayland-server.h
View file

@ -23,10 +23,13 @@
* SOFTWARE. * SOFTWARE.
*/ */
/** \file
/** Use of this header file is discouraged. Prefer including *
* \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 * 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. * API, excluding the deprecated API below.
*/ */