* it will assume the file descriptor is readable and read events from
* the fd by calling wl_display_dispatch(). Simplified, we have:
*
- * wl_display_dispatch_pending(display);
- * wl_display_flush(display);
- * poll(fds, nfds, -1);
- * wl_display_dispatch(display);
+ * \code
+ * wl_display_dispatch_pending(display);
+ * wl_display_flush(display);
+ * poll(fds, nfds, -1);
+ * wl_display_dispatch(display);
+ * \endcode
*
* There are two races here: first, before blocking in poll(), the fd
* could become readable and another thread reads the events. Some of
* fds in the event loop.
*
* A correct sequence would be:
- *
- * while (wl_display_prepare_read(display) != 0)
- * wl_display_dispatch_pending(display);
- * wl_display_flush(display);
- * poll(fds, nfds, -1);
- * wl_display_read_events(display);
- * wl_display_dispatch_pending(display);
+ * \code
+ * while (wl_display_prepare_read(display) != 0)
+ * wl_display_dispatch_pending(display);
+ * wl_display_flush(display);
+ * poll(fds, nfds, -1);
+ * wl_display_read_events(display);
+ * wl_display_dispatch_pending(display);
+ * \endcode
*
* Here we call wl_display_prepare_read(), which ensures that between
* returning from that call and eventually calling
* listener should be done through provided accessor methods. A listener can
* only listen to one signal at a time.
*
- * ~~~
+ * \code
* struct wl_listener your_listener;
*
* your_listener.notify = your_callback_method;
*
- * \comment{Direct access}
+ * // Direct access
* wl_signal_add(&some_object->destroy_signal, &your_listener);
*
- * \comment{Accessor access}
+ * // Accessor access
* wl_event_loop *loop = ...;
* wl_event_loop_add_destroy_listener(loop, &your_listener);
- * ~~~
+ * \endcode
*
* If the listener is part of a larger struct, #wl_container_of can be used
* to retrieve a pointer to it:
* "item_t", and the item member as "struct wl_list link".
*
* The following code will initialize a list:
- *
- * ~~~
+ * \code
* struct wl_list foo_list;
*
* struct item_t {
* struct item_t item1, item2, item3;
*
* wl_list_init(&foo_list);
- * wl_list_insert(&foo_list, &item1.link); \comment{Pushes item1 at the head}
- * wl_list_insert(&foo_list, &item2.link); \comment{Pushes item2 at the head}
- * wl_list_insert(&item2.link, &item3.link); \comment{Pushes item3 after item2}
- * ~~~
+ * wl_list_insert(&foo_list, &item1.link); // Pushes item1 at the head
+ * wl_list_insert(&foo_list, &item2.link); // Pushes item2 at the head
+ * wl_list_insert(&item2.link, &item3.link); // Pushes item3 after item2
+ * \endcode
*
* The list now looks like [item2, item3, item1]
*
- * Will iterate the list in ascending order:
- *
+ * Iterate the list in ascending order:
* \code
- * item_t *item;
- * wl_list_for_each(item, foo_list, link) {
- * Do_something_with_item(item);
- * }
+ * item_t *item;
+ * wl_list_for_each(item, foo_list, link) {
+ * Do_something_with_item(item);
+ * }
* \endcode
*/
struct wl_list {
* To demonstrate, the following example retrieves a pointer to
* `example_container` given only its `destroy_listener` member:
*
- * ~~~
+ * \code
* struct example_container {
* struct wl_listener destroy_listener;
- * \comment{other members...}
+ * // other members...
* };
*
* void example_container_destroy(struct wl_listener *listener, void *data)
* struct example_container *ctr;
*
* ctr = wl_container_of(listener, ctr, destroy_listener);
- * \comment{destroy ctr...}
+ * // destroy ctr...
* }
- * ~~~
+ * \endcode
*
* \param ptr A valid pointer to the contained item.
*