include: Reorg doxygen for waffle_config_choose

Users want to see a quick example before diving into the documentation's
details, so move the example from the bottom to the top.

Also, remove @return and @param. These were redundant and out of place.

Signed-off-by: Chad Versace <chad.versace@linux.intel.com>

1 files changed, 27 insertions, 32 deletions

diff --git a/include/waffle/waffle_config.h b/include/waffle/waffle_config.h
index f5eeab6..f27baa3 100644
--- a/include/waffle/waffle_config.h
+++ b/include/waffle/waffle_config.h
@@ -35,6 +35,33 @@ struct waffle_display;
 /// @brief Choose a config satisfying some attributes.
 ///
 ///
+/// ### Example Attribute Lists ###
+///
+/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
+/// const int32_t empty_list[] = {0};
+///
+/// const int32_t opengl32_rgb565[] = {
+///     WAFFLE_CONTEXT_API,             WAFFLE_CONTEXT_OPENGL,
+///     WAFFLE_CONTEXT_MAJOR_VERSION,   3,
+///     WAFFLE_CONTEXT_MINOR_VERSION,   2,
+///     WAFFLE_CONTEXT_PROFILE,         WAFFLE_CONTEXT_CORE_PROFILE,
+///
+///     WAFFLE_RED_SIZE,    5,
+///     WAFFLE_GREEN_SIZE,  6,
+///     WAFFLE_BLUE_SIZE,   5,
+///     0,
+/// };
+///
+/// const int32_t opengles2_z24s8[] = {
+///     WAFFLE_CONTEXT_API,      WAFFLE_CONTEXT_OPENGL_ES2,
+///
+///     WAFFLE_DEPTH_SIZE,      24,
+///     WAFFLE_STENCIL_SIZE,     8,
+///     0,
+/// };
+/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+///
+///
 /// ### Attributes ###
 ///
 /// Argument @a attrib_list specifies a list of attributes, described in the
@@ -164,38 +191,6 @@ struct waffle_display;
 /// | .                                       |    . |                . | .                                             |
 /// | WAFFLE_DOUBLE_BUFFERED                  | bool |             true | .                                             |
 ///
-///
-/// ### Example Attribute Lists ###
-///
-/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
-/// const int32_t empty_list[] = {0};
-///
-/// const int32_t opengl32_rgb565[] = {
-///     WAFFLE_CONTEXT_API,             WAFFLE_CONTEXT_OPENGL,
-///     WAFFLE_CONTEXT_MAJOR_VERSION,   3,
-///     WAFFLE_CONTEXT_MINOR_VERSION,   2,
-///     WAFFLE_CONTEXT_PROFILE,         WAFFLE_CONTEXT_CORE_PROFILE,
-///
-///     WAFFLE_RED_SIZE,    5,
-///     WAFFLE_GREEN_SIZE,  6,
-///     WAFFLE_BLUE_SIZE,   5,
-///     0,
-/// };
-///
-/// const int32_t opengles2_z24s8[] = {
-///     WAFFLE_CONTEXT_API,      WAFFLE_CONTEXT_OPENGL_ES2,
-///
-///     WAFFLE_DEPTH_SIZE,      24,
-///     WAFFLE_STENCIL_SIZE,     8,
-///     0,
-/// };
-/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-///
-///
-/// @return A config that satisfies @a attrib_list. If no such config is
-///     found, return null.
-/// @see waffle_enum
-///
 WAFFLE_API struct waffle_config*
 waffle_config_choose(struct waffle_display *dpy, const int32_t attrib_list[]);