BASELINE: Update Chromium to 60.0.3112.78

Change-Id: I58f9d14bddb9104a666b6ef869944111ee7eadb8
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>

11 files changed, 219 insertions, 88 deletions

diff --git a/chromium/third_party/wayland/src/Makefile.am b/chromium/third_party/wayland/src/Makefile.am
index d35231cd33b..d78a0ca5ef6 100644
--- a/chromium/third_party/wayland/src/Makefile.am
+++ b/chromium/third_party/wayland/src/Makefile.am
@@ -151,6 +151,7 @@ built_test_programs =				\
 	connection-test				\
 	event-loop-test				\
 	fixed-test				\
+	interface-test				\
 	list-test				\
 	map-test				\
 	os-wrappers-test			\
@@ -168,16 +169,22 @@ if ENABLE_CPP_TEST
 built_test_programs += cpp-compile-test
 endif
 
-TESTS = $(built_test_programs)
+AM_TESTS_ENVIRONMENT =							\
+	export WAYLAND_SCANNER='$(top_builddir)/wayland-scanner'	\
+	TEST_DATA_DIR='$(top_srcdir)/tests/data'			\
+	TEST_OUTPUT_DIR='$(top_builddir)/tests/output'			\
+	SED=$(SED)							\
+	;
 
-check_PROGRAMS =				\
-	$(built_test_programs)			\
-	exec-fd-leak-checker
+TESTS = $(built_test_programs)			\
+	tests/scanner-test.sh
 
 noinst_PROGRAMS =				\
+	$(built_test_programs)			\
+	exec-fd-leak-checker			\
 	fixed-benchmark
 
-check_LTLIBRARIES = libtest-runner.la
+noinst_LTLIBRARIES += libtest-runner.la
 
 libtest_runner_la_SOURCES =			\
 	tests/test-runner.c			\
@@ -205,6 +212,8 @@ event_loop_test_SOURCES = tests/event-loop-test.c
 event_loop_test_LDADD = libtest-runner.la
 fixed_test_SOURCES = tests/fixed-test.c
 fixed_test_LDADD = libtest-runner.la
+interface_test_SOURCES = tests/interface-test.c
+interface_test_LDADD = libtest-runner.la
 list_test_SOURCES = tests/list-test.c
 list_test_LDADD = libtest-runner.la
 map_test_SOURCES = tests/map-test.c
@@ -245,4 +254,23 @@ os_wrappers_test_LDADD = libtest-runner.la
 
 exec_fd_leak_checker_SOURCES = tests/exec-fd-leak-checker.c
 exec_fd_leak_checker_LDADD = libtest-runner.la
+
+EXTRA_DIST += tests/scanner-test.sh			\
+	tests/data/example.xml				\
+	tests/data/example-client.h			\
+	tests/data/example-server.h			\
+	tests/data/example-code.c			\
+	tests/data/small.xml				\
+	tests/data/small-code.c				\
+	tests/data/small-client.h			\
+	tests/data/small-server.h			\
+	tests/data/small-code-core.c			\
+	tests/data/small-client-core.h			\
+	tests/data/small-server-core.h
+
+tests/scanner-test.sh: $(top_builddir)/wayland-scanner
+
+clean-local:
+	-rm -rf tests/output
+
 endif #ENABLE_LIBRARIES
diff --git a/chromium/third_party/wayland/src/cursor/os-compatibility.c b/chromium/third_party/wayland/src/cursor/os-compatibility.c
index d7d4b33b43b..e972d219587 100644
--- a/chromium/third_party/wayland/src/cursor/os-compatibility.c
+++ b/chromium/third_party/wayland/src/cursor/os-compatibility.c
@@ -103,7 +103,7 @@ create_tmpfile_cloexec(char *tmpname)
 int
 os_create_anonymous_file(off_t size)
 {
-	static const char template[] = "/weston-shared-XXXXXX";
+	static const char template[] = "/wayland-cursor-shared-XXXXXX";
 	const char *path;
 	char *name;
 	int fd;
diff --git a/chromium/third_party/wayland/src/doc/doxygen/Makefile.am b/chromium/third_party/wayland/src/doc/doxygen/Makefile.am
index c3773536230..276a395bfbf 100644
--- a/chromium/third_party/wayland/src/doc/doxygen/Makefile.am
+++ b/chromium/third_party/wayland/src/doc/doxygen/Makefile.am
@@ -9,7 +9,6 @@ noinst_DATA = \
 dist_noinst_DATA = wayland.doxygen.in
 
 scanned_src_files_shared = 				\
-	$(top_srcdir)/src/wayland-util.c	\
 	$(top_srcdir)/src/wayland-util.h
 
 scanned_src_files_Client = 				\
diff --git a/chromium/third_party/wayland/src/doc/doxygen/wayland.doxygen.in b/chromium/third_party/wayland/src/doc/doxygen/wayland.doxygen.in
index 9d7fa0c40f1..3913a135789 100644
--- a/chromium/third_party/wayland/src/doc/doxygen/wayland.doxygen.in
+++ b/chromium/third_party/wayland/src/doc/doxygen/wayland.doxygen.in
@@ -8,7 +8,8 @@ QUIET                  = YES
 HTML_TIMESTAMP         = YES
 GENERATE_LATEX         = NO
 MAN_LINKS              = YES
-PREDEFINED             = WL_EXPORT=
+PREDEFINED             = WL_EXPORT=              \
+                         WL_PRINTF(x,y)=
 MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
 DOT_MULTI_TARGETS      = YES
diff --git a/chromium/third_party/wayland/src/doc/publican/sources/Client.xml b/chromium/third_party/wayland/src/doc/publican/sources/Client.xml
index fcdd2f2f0ba..19bf3e9572a 100644
--- a/chromium/third_party/wayland/src/doc/publican/sources/Client.xml
+++ b/chromium/third_party/wayland/src/doc/publican/sources/Client.xml
@@ -30,7 +30,7 @@
     object created.
   </para>
   <para>
-    Though some conveinence functions are provided, libwayland-client
+    Though some convenience functions are provided, libwayland-client
     is designed to allow the calling code to wait for events, so that
     different polling mechanisms can be used. A file descriptor is
     provided, when it becomes ready for reading the calling code can
diff --git a/chromium/third_party/wayland/src/protocol/wayland.xml b/chromium/third_party/wayland/src/protocol/wayland.xml
index 8311a18de1f..098f286bab7 100644
--- a/chromium/third_party/wayland/src/protocol/wayland.xml
+++ b/chromium/third_party/wayland/src/protocol/wayland.xml
@@ -129,7 +129,7 @@
     <request name="bind">
       <description summary="bind an object to the display">
 	Binds a new, client-created object to the server using the
-        specified name as the identifier.
+	specified name as the identifier.
       </description>
       <arg name="name" type="uint" summary="unique numeric name of the object"/>
       <arg name="id" type="new_id" summary="bounded object"/>
@@ -139,9 +139,9 @@
       <description summary="announce global object">
 	Notify the client of global objects.
 
-        The event notifies the client that a global object with
-        the given name is now available, and it implements the
-        given version of the given interface.
+	The event notifies the client that a global object with
+	the given name is now available, and it implements the
+	given version of the given interface.
       </description>
       <arg name="name" type="uint" summary="numeric name of the global object"/>
       <arg name="interface" type="string" summary="interface implemented by the object"/>
@@ -152,10 +152,10 @@
       <description summary="announce removal of global object">
 	Notify the client of removed global objects.
 
-        This event notifies the client that the global identified
-        by name is no longer available.  If the client bound to
-        the global using the bind request, the client should now
-        destroy that object.
+	This event notifies the client that the global identified
+	by name is no longer available.  If the client bound to
+	the global using the bind request, the client should now
+	destroy that object.
 
 	The object remains valid and requests to the object will be
 	ignored until the client destroys it, to avoid races between
@@ -355,7 +355,7 @@
 
 	The pool can be used to create shared memory based buffer
 	objects.  The server will mmap size bytes of the passed file
-        descriptor, to use as backing memory for the pool.
+	descriptor, to use as backing memory for the pool.
       </description>
       <arg name="id" type="new_id" interface="wl_shm_pool" summary="pool to create"/>
       <arg name="fd" type="fd" summary="file descriptor for the pool"/>
@@ -915,14 +915,14 @@
 
     <request name="create_data_source">
       <description summary="create a new data source">
-        Create a new data source.
+	Create a new data source.
       </description>
       <arg name="id" type="new_id" interface="wl_data_source" summary="data source to create"/>
     </request>
 
     <request name="get_data_device">
       <description summary="create a new data device">
-        Create a new data device for a given seat.
+	Create a new data device for a given seat.
       </description>
       <arg name="id" type="new_id" interface="wl_data_device" summary="data device to create"/>
       <arg name="seat" type="object" interface="wl_seat" summary="seat associated with the data device"/>
@@ -1308,7 +1308,7 @@
 
     <enum name="error">
       <description summary="wl_surface error values">
-        These errors can be emitted in response to wl_surface requests.
+	These errors can be emitted in response to wl_surface requests.
       </description>
       <entry name="invalid_scale" value="0" summary="buffer scale value is invalid"/>
       <entry name="invalid_transform" value="1" summary="buffer transform value is invalid"/>
@@ -1661,8 +1661,8 @@
 
     <enum name="capability" bitfield="true">
       <description summary="seat capability bitmask">
-        This is a bitmask of capabilities this seat has; if a member is
-        set, then it is present on the seat.
+	This is a bitmask of capabilities this seat has; if a member is
+	set, then it is present on the seat.
       </description>
       <entry name="pointer" value="1" summary="the seat has pointer devices"/>
       <entry name="keyboard" value="2" summary="the seat has one or more keyboards"/>
@@ -1857,7 +1857,7 @@
 
     <enum name="button_state">
       <description summary="physical button state">
-        Describes the physical state of a button that produced the button
+	Describes the physical state of a button that produced the button
 	event.
       </description>
       <entry name="released" value="0" summary="the button is not pressed"/>
@@ -1870,8 +1870,16 @@
 
 	The location of the click is given by the last motion or
 	enter event.
-        The time argument is a timestamp with millisecond
-        granularity, with an undefined base.
+	The time argument is a timestamp with millisecond
+	granularity, with an undefined base.
+
+	The button is a button code as defined in the Linux kernel's
+	linux/input-event-codes.h header file, e.g. BTN_LEFT.
+
+	Any 16-bit button code value is reserved for future additions to the
+	kernel's event code list. All other button codes above 0xFFFF are
+	currently undefined but may be used in future versions of this
+	protocol.
       </description>
       <arg name="serial" type="uint" summary="serial number of the button event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
@@ -2083,7 +2091,7 @@
       <entry name="no_keymap" value="0"
 	     summary="no keymap; client must understand how to interpret the raw keycode"/>
       <entry name="xkb_v1" value="1"
-             summary="libxkbcommon compatible; to determine the xkb keycode, clients must add 8 to the key event keycode"/>
+	     summary="libxkbcommon compatible; to determine the xkb keycode, clients must add 8 to the key event keycode"/>
     </enum>
 
     <event name="keymap">
@@ -2129,8 +2137,8 @@
     <event name="key">
       <description summary="key event">
 	A key was pressed or released.
-        The time argument is a timestamp with millisecond
-        granularity, with an undefined base.
+	The time argument is a timestamp with millisecond
+	granularity, with an undefined base.
       </description>
       <arg name="serial" type="uint" summary="serial number of the key event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
@@ -2160,23 +2168,23 @@
 
     <event name="repeat_info" since="4">
       <description summary="repeat rate and delay">
-        Informs the client about the keyboard's repeat rate and delay.
+	Informs the client about the keyboard's repeat rate and delay.
 
-        This event is sent as soon as the wl_keyboard object has been created,
-        and is guaranteed to be received by the client before any key press
-        event.
+	This event is sent as soon as the wl_keyboard object has been created,
+	and is guaranteed to be received by the client before any key press
+	event.
 
-        Negative values for either rate or delay are illegal. A rate of zero
-        will disable any repeating (regardless of the value of delay).
+	Negative values for either rate or delay are illegal. A rate of zero
+	will disable any repeating (regardless of the value of delay).
 
-        This event can be sent later on as well with a new value if necessary,
-        so clients should continue listening for the event past the creation
-        of wl_keyboard.
+	This event can be sent later on as well with a new value if necessary,
+	so clients should continue listening for the event past the creation
+	of wl_keyboard.
       </description>
       <arg name="rate" type="int"
-           summary="the rate of repeating keys in characters per second"/>
+	   summary="the rate of repeating keys in characters per second"/>
       <arg name="delay" type="int"
-           summary="delay in milliseconds since key down until repeating starts"/>
+	   summary="delay in milliseconds since key down until repeating starts"/>
     </event>
   </interface>
 
@@ -2417,10 +2425,10 @@
 	mode that was received with the current flag set.
 
 	The size of a mode is given in physical hardware units of
-        the output device. This is not necessarily the same as
-        the output size in the global compositor space. For instance,
-        the output may be scaled, as described in wl_output.scale,
-        or transformed, as described in wl_output.transform.
+	the output device. This is not necessarily the same as
+	the output size in the global compositor space. For instance,
+	the output may be scaled, as described in wl_output.scale,
+	or transformed, as described in wl_output.transform.
       </description>
       <arg name="flags" type="uint" enum="mode" summary="bitfield of mode flags"/>
       <arg name="width" type="int" summary="width of the mode in hardware units"/>
@@ -2432,20 +2440,20 @@
 
     <event name="done" since="2">
       <description summary="sent all information about output">
-        This event is sent after all other properties have been
-        sent after binding to the output object and after any
-        other property changes done after that. This allows
-        changes to the output properties to be seen as
-        atomic, even if they happen via multiple events.
+	This event is sent after all other properties have been
+	sent after binding to the output object and after any
+	other property changes done after that. This allows
+	changes to the output properties to be seen as
+	atomic, even if they happen via multiple events.
       </description>
     </event>
 
     <event name="scale" since="2">
       <description summary="output scaling properties">
 	This event contains scaling geometry information
-        that is not in the geometry event. It may be sent after
-        binding the output object or if the output scale changes
-        later. If it is not sent, the client should assume a
+	that is not in the geometry event. It may be sent after
+	binding the output object or if the output scale changes
+	later. If it is not sent, the client should assume a
 	scale of 1.
 
 	A scale larger than 1 means that the compositor will
@@ -2542,7 +2550,7 @@
 
     <enum name="error">
       <entry name="bad_surface" value="0"
-             summary="the to-be sub-surface is invalid"/>
+	     summary="the to-be sub-surface is invalid"/>
     </enum>
 
     <request name="get_subsurface">
@@ -2556,11 +2564,11 @@
 	error is raised.
       </description>
       <arg name="id" type="new_id" interface="wl_subsurface"
-           summary="the new sub-surface object ID"/>
+	   summary="the new sub-surface object ID"/>
       <arg name="surface" type="object" interface="wl_surface"
-           summary="the surface to be turned into a sub-surface"/>
+	   summary="the surface to be turned into a sub-surface"/>
       <arg name="parent" type="object" interface="wl_surface"
-           summary="the parent surface"/>
+	   summary="the parent surface"/>
     </request>
   </interface>
 
@@ -2629,7 +2637,7 @@
 
     <enum name="error">
       <entry name="bad_surface" value="0"
-             summary="wl_surface is not a sibling or the parent"/>
+	     summary="wl_surface is not a sibling or the parent"/>
     </enum>
 
     <request name="set_position">
@@ -2674,7 +2682,7 @@
 	of its siblings and parent.
       </description>
       <arg name="sibling" type="object" interface="wl_surface"
-           summary="the reference surface"/>
+	   summary="the reference surface"/>
     </request>
 
     <request name="place_below">
@@ -2683,7 +2691,7 @@
 	See wl_subsurface.place_above.
       </description>
       <arg name="sibling" type="object" interface="wl_surface"
-           summary="the reference surface"/>
+	   summary="the reference surface"/>
     </request>
 
     <request name="set_sync">
diff --git a/chromium/third_party/wayland/src/src/wayland-client-uninstalled.pc.in b/chromium/third_party/wayland/src/src/wayland-client-uninstalled.pc.in
index 3086621da4e..732736e94a3 100644
--- a/chromium/third_party/wayland/src/src/wayland-client-uninstalled.pc.in
+++ b/chromium/third_party/wayland/src/src/wayland-client-uninstalled.pc.in
@@ -1,8 +1,9 @@
 libdir=@abs_builddir@/.libs
 includedir=@abs_srcdir@
+protocoldir=@abs_top_builddir@/protocol
  
 Name: Wayland Client
 Description: Wayland client side library (not installed)
 Version: @PACKAGE_VERSION@
-Cflags: -I${includedir}
+Cflags: -I${includedir} -I${protocoldir}
 Libs: -L${libdir} -lwayland-client
diff --git a/chromium/third_party/wayland/src/src/wayland-client.c b/chromium/third_party/wayland/src/src/wayland-client.c
index 03c087a66ae..3d7361ea943 100644
--- a/chromium/third_party/wayland/src/src/wayland-client.c
+++ b/chromium/third_party/wayland/src/src/wayland-client.c
@@ -1006,7 +1006,7 @@ wl_display_connect(const char *name)
 	if (connection) {
 		int prev_errno = errno;
 		errno = 0;
-		fd = strtol(connection, &end, 0);
+		fd = strtol(connection, &end, 10);
 		if (errno != 0 || connection == end || *end != '\0')
 			return NULL;
 		errno = prev_errno;
diff --git a/chromium/third_party/wayland/src/src/wayland-scanner-uninstalled.pc.in b/chromium/third_party/wayland/src/src/wayland-scanner-uninstalled.pc.in
index 8dcfef31541..132f42d0616 100644
--- a/chromium/third_party/wayland/src/src/wayland-scanner-uninstalled.pc.in
+++ b/chromium/third_party/wayland/src/src/wayland-scanner-uninstalled.pc.in
@@ -1,5 +1,5 @@
 pkgdatadir=@abs_top_srcdir@
-wayland_scanner=@abs_builddir@/wayland-scanner
+wayland_scanner=@abs_top_builddir@/wayland-scanner
  
 Name: Wayland Scanner
 Description: Wayland scanner (not installed)
diff --git a/chromium/third_party/wayland/src/src/wayland-server-uninstalled.pc.in b/chromium/third_party/wayland/src/src/wayland-server-uninstalled.pc.in
index 90577828cac..562686c31d1 100644
--- a/chromium/third_party/wayland/src/src/wayland-server-uninstalled.pc.in
+++ b/chromium/third_party/wayland/src/src/wayland-server-uninstalled.pc.in
@@ -1,8 +1,9 @@
 libdir=@abs_builddir@/.libs
 includedir=@abs_srcdir@
+protocoldir=@abs_top_builddir@/protocol
  
 Name: Wayland Server
 Description: Server side implementation of the Wayland protocol (not installed)
 Version: @PACKAGE_VERSION@
-Cflags: -I${includedir}
+Cflags: -I${includedir} -I${protocoldir}
 Libs: -L${libdir} -lwayland-server
diff --git a/chromium/third_party/wayland/src/src/wayland-util.h b/chromium/third_party/wayland/src/src/wayland-util.h
index 50f3372a942..caeac826738 100644
--- a/chromium/third_party/wayland/src/src/wayland-util.h
+++ b/chromium/third_party/wayland/src/src/wayland-util.h
@@ -142,12 +142,64 @@ struct wl_message {
 	const struct wl_interface **types;
 };
 
+/**
+ * Protocol object interface
+ *
+ * A wl_interface describes the API of a protocol object defined in the Wayland
+ * protocol specification. The protocol implementation uses a wl_interface
+ * within its marshalling machinery for encoding client requests.
+ *
+ * The `name` of a wl_interface is the name of the corresponding protocol
+ * interface, and `version` represents the version of the interface. The members
+ * `method_count` and `event_count` represent the number of `methods` (requests)
+ * and `events` in the respective wl_message members.
+ *
+ * For example, consider a protocol interface `foo`, marked as version `1`, with
+ * two requests and one event.
+ *
+ * \code
+ * <interface name="foo" version="1">
+ *   <request name="a"></request>
+ *   <request name="b"></request>
+ *   <event name="c"></event>
+ * </interface>
+ * \endcode
+ *
+ * Given two wl_message arrays `foo_requests` and `foo_events`, a wl_interface
+ * for `foo` might be:
+ *
+ * \code
+ * struct wl_interface foo_interface = {
+ *         "foo", 1,
+ *         2, foo_requests,
+ *         1, foo_events
+ * };
+ * \endcode
+ *
+ * \note The server side of the protocol may define interface <em>implementation
+ *       types</em> that incorporate the term `interface` in their name. Take
+ *       care to not confuse these server-side `struct`s with a wl_interface
+ *       variable whose name also ends in `interface`. For example, while the
+ *       server may define a type `struct wl_foo_interface`, the client may
+ *       define a `struct wl_interface wl_foo_interface`.
+ *
+ * \sa wl_message
+ * \sa wl_proxy
+ * \sa <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Interfaces">Interfaces</a>
+ * \sa <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Versioning">Versioning</a>
+ */
 struct wl_interface {
+	/** Interface name */
 	const char *name;
+	/** Interface version */
 	int version;
+	/** Number of methods (requests) */
 	int method_count;
+	/** Method (request) signatures */
 	const struct wl_message *methods;
+	/** Number of events */
 	int event_count;
+	/** Event signatures */
 	const struct wl_message *events;
 };
 
@@ -209,7 +261,9 @@ struct wl_interface {
  * \sa http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/linux/list.h
  */
 struct wl_list {
+	/** Previous list element */
 	struct wl_list *prev;
+	/** Next list element */
 	struct wl_list *next;
 };
 
@@ -438,8 +492,11 @@ wl_list_insert_list(struct wl_list *list, struct wl_list *other);
  *
  */
 struct wl_array {
+	/** Array size */
 	size_t size;
+	/** Allocated space */
 	size_t alloc;
+	/** Array data */
 	void *data;
 };
 
@@ -588,50 +645,86 @@ wl_fixed_from_int(int i)
 }
 
 /**
- * \brief A union representing all of the basic data types that can be passed
- * along the wayland wire format.
+ * Protocol message argument data types
  *
- * This union represents all of the basic data types that can be passed in the
- * wayland wire format.  It is used by dispatchers and runtime-friendly
- * versions of the event and request marshaling functions.
+ * This union represents all of the argument types in the Wayland protocol wire
+ * format. The protocol implementation uses wl_argument within its marshalling
+ * machinery for dispatching messages between a client and a compositor.
+ *
+ * \sa wl_message
+ * \sa wl_interface
+ * \sa <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-wire-Format">Wire Format</a>
  */
 union wl_argument {
-	int32_t i; /**< signed integer */
-	uint32_t u; /**< unsigned integer */
-	wl_fixed_t f; /**< fixed point */
-	const char *s; /**< string */
-	struct wl_object *o; /**< object */
-	uint32_t n; /**< new_id */
-	struct wl_array *a; /**< array */
-	int32_t h; /**< file descriptor */
+	int32_t i;           /**< `int`    */
+	uint32_t u;          /**< `uint`   */
+	wl_fixed_t f;        /**< `fixed`  */
+	const char *s;       /**< `string` */
+	struct wl_object *o; /**< `object` */
+	uint32_t n;          /**< `new_id` */
+	struct wl_array *a;  /**< `array`  */
+	int32_t h;           /**< `fd`     */
 };
 
 /**
- * \brief A function pointer type for a dispatcher.
+ * Dispatcher function type alias
  *
  * A dispatcher is a function that handles the emitting of callbacks in client
- * code.  For programs directly using the C library, this is done by using
- * libffi to call function pointers.  When binding to languages other than C,
+ * code. For programs directly using the C library, this is done by using
+ * libffi to call function pointers. When binding to languages other than C,
  * dispatchers provide a way to abstract the function calling process to be
  * friendlier to other function calling systems.
  *
- * A dispatcher takes five arguments:  The first is the dispatcher-specific
- * implementation data associated with the target object.  The second is the
- * object on which the callback is being invoked (either wl_proxy or
- * wl_resource).  The third and fourth arguments are the opcode the wl_message
- * structure corresponding to the callback being emitted.  The final argument
- * is an array of arguments received from the other process via the wire
- * protocol.
+ * A dispatcher takes five arguments: The first is the dispatcher-specific
+ * implementation associated with the target object. The second is the object
+ * upon which the callback is being invoked (either wl_proxy or wl_resource).
+ * The third and fourth arguments are the opcode and the wl_message
+ * corresponding to the callback. The final argument is an array of arguments
+ * received from the other process via the wire protocol.
+ *
+ * \param "const void *" Dispatcher-specific implementation data
+ * \param "void *" Callback invocation target (wl_proxy or `wl_resource`)
+ * \param uint32_t Callback opcode
+ * \param "const struct wl_message *" Callback message signature
+ * \param "union wl_argument *" Array of received arguments
+ *
+ * \return 0 on success, or -1 on failure
  */
 typedef int (*wl_dispatcher_func_t)(const void *, void *, uint32_t,
 				    const struct wl_message *,
 				    union wl_argument *);
 
+/**
+ * Log function type alias
+ *
+ * The C implementation of the Wayland protocol abstracts the details of
+ * logging. Users may customize the logging behavior, with a function conforming
+ * to the `wl_log_func_t` type, via `wl_log_set_handler_client` and
+ * `wl_log_set_handler_server`.
+ *
+ * A `wl_log_func_t` must conform to the expectations of `vprintf`, and
+ * expects two arguments: a string to write and a corresponding variable
+ * argument list. While the string to write may contain format specifiers and
+ * use values in the variable argument list, the behavior of any `wl_log_func_t`
+ * depends on the implementation.
+ *
+ * \note Take care to not confuse this with `wl_protocol_logger_func_t`, which
+ *       is a specific server-side logger for requests and events.
+ *
+ * \param "const char *" String to write to the log, containing optional format
+ *                       specifiers
+ * \param "va_list" Variable argument list
+ *
+ * \sa wl_log_set_handler_client
+ * \sa wl_log_set_handler_server
+ */
 typedef void (*wl_log_func_t)(const char *, va_list) WL_PRINTF(1, 0);
 
-/** \enum wl_iterator_result
+/**
+ * Return value of an iterator function
  *
- * This enum represents the return value of an iterator function.
+ * \sa wl_client_for_each_resource_iterator_func_t
+ * \sa wl_client_for_each_resource
  */
 enum wl_iterator_result {
 	/** Stop the iteration */