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

[Bryce Harrington]

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>

> ---
>  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