diff --git a/src/wayland-client.h b/src/wayland-client.h
index 38565357..9f70fa3f 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 b6d0e2bc..31247031 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.
  */