On Wed, 18 Jan 2012 12:29:37 -0800
"Kristensen, Kristian H" <kristian.h.kristensen@intel.com> wrote:
> Yeah, that looks good.  I was thinking of a separate <description> tag
> to avoid stuffing too much into an attribute.

How does this look?  It adds a summary attribute to atomic elements,
and a <description> tag with a summary for others.  Spits out enum
documentation like this:

/**
 * wl_display_error - global error values
 * @WL_DISPLAY_ERROR_INVALID_OBJECT: server couldn't find object
 * @WL_DISPLAY_ERROR_INVALID_METHOD: method doesn't exist on the specified interface
 * @WL_DISPLAY_ERROR_NO_MEMORY: server is out of memory
 *
 * These errors are global and can be emitted in response to any server request.
 */
enum wl_display_error {
	WL_DISPLAY_ERROR_INVALID_OBJECT = 0,
	WL_DISPLAY_ERROR_INVALID_METHOD = 1,
	WL_DISPLAY_ERROR_NO_MEMORY = 2,
};

and structure documentation like this:

/**
 * wl_display - core global object
 * @bind: bind an object to the display
 * @sync: (none)
 *
 * The core global object. This is a special singleton object. It is used for
 * internal wayland protocol features.
 */
struct wl_display_interface {
	void (*bind)(struct wl_client *client,
		     struct wl_resource *resource,
		     uint32_t name,
		     const char *interface,
		     uint32_t version,
		     uint32_t id);
	void (*sync)(struct wl_client *client,
		     struct wl_resource *resource,
		     uint32_t callback);
};