include: Remove doxygen from public headers

The recently added man pages were based on this doxygen and are now the
canonical source of user documentation. Delete the doxygen so it doesn't
drift out-of-sync with with the man pages.

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

11 files changed, 0 insertions, 435 deletions

diff --git a/include/waffle/waffle.h b/include/waffle/waffle.h
index 6158af3..c086799 100644
--- a/include/waffle/waffle.h
+++ b/include/waffle/waffle.h
@@ -23,14 +23,6 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-/// @defgroup waffle_api waffle_api
-///
-/// @brief Waffle's public API
-/// @{
-
-/// @file
-/// @brief Convenience header to include all waffle headers.
-
 #pragma once
 
 #include "waffle_version.h"
@@ -46,5 +38,3 @@
 #include "waffle_init.h"
 #include "waffle_portability.h"
 #include "waffle_window.h"
-
-/// @}
diff --git a/include/waffle/waffle_attrib_list.h b/include/waffle/waffle_attrib_list.h
index cc3d855..c7f059d 100644
--- a/include/waffle/waffle_attrib_list.h
+++ b/include/waffle/waffle_attrib_list.h
@@ -23,16 +23,6 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-/// @defgroup waffle_attrib_list waffle_attrib_list
-/// @ingroup waffle_api
-///
-/// @brief Utilities for attribute lists
-///
-/// All functions in this module set the error code to WAFFLE_NO_ERROR.
-/// @{
-
-/// @file
-
 #pragma once
 
 #include <stdbool.h>
@@ -47,18 +37,12 @@ extern "C" {
 WAFFLE_API int32_t
 waffle_attrib_list_length(const int32_t attrib_list[]);
 
-/// If the @a key is not found, then @a value is not modified.
-///
-/// @return true if key was found.
 WAFFLE_API bool
 waffle_attrib_list_get(
         const int32_t attrib_list[],
         int32_t key,
         int32_t *value);
 
-/// If the @a key is not found, the @a value is set to default.
-///
-/// @return true if @a key was found.
 WAFFLE_API bool
 waffle_attrib_list_get_with_default(
         const int32_t attrib_list[],
@@ -66,7 +50,6 @@ waffle_attrib_list_get_with_default(
         int32_t *value,
         int32_t default_value);
 
-/// @return false if @a key is not found.
 WAFFLE_API bool
 waffle_attrib_list_update(
         int32_t *attrib_list,
@@ -76,5 +59,3 @@ waffle_attrib_list_update(
 #ifdef __cplusplus
 } // end extern "C"
 #endif
-
-/// @}
diff --git a/include/waffle/waffle_config.h b/include/waffle/waffle_config.h
index 58414c0..6f352a2 100644
--- a/include/waffle/waffle_config.h
+++ b/include/waffle/waffle_config.h
@@ -23,12 +23,6 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-/// @defgroup waffle_config waffle_config
-/// @ingroup waffle_api
-/// @{
-
-/// @file
-
 #pragma once
 
 #include <stdbool.h>
@@ -55,180 +49,15 @@ union waffle_native_config {
     struct waffle_wayland_config *wayland;
 };
 
-/// @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
-/// table below, that the returned config must satisfy. The list consists of
-/// a zero-terminated sequence of name/value pairs. If an attribute is absent
-/// from the list, then the attribute assumes its default value. If @a
-/// attrib_list is null or empty, then all attributes assume their default
-/// values.
-///
-/// Individual attributes are discussed below.
-///
-/// The context attributes (`WAFFLE_CONTEXT_*`) have quirks that are specific
-/// to the native platform. Waffle attempts to accomdate those quirks in
-/// a platform-neutral way as much as possible, but not all quirks can be
-/// eliminated through a platform abstraction layer. The quirks are documented
-/// below in detail.  For additional documentation on the behavior of the
-/// contxt attributes on each platform, refer to the following: for GLX, refer
-/// to the [GLX_ARB_create_context_profile] and
-/// [GLX_EXT_create_context_es2_profile] extensions; for EGL, refer to the
-/// [EGL 1.4 specification]; for CGL, refer to the documentation of
-/// `kCGLPFAOpenGLProfile` in Apple's [CGL Reference].
-///
-/// For example, one quirk that Waffle is able to accomodate is that some
-/// platforms require specification of context attributes at different times.
-/// GLX requires that the context attributes be specified at time of context
-/// creation (`glXCreateContextAttribsARB`), but MacOS requires the attributes
-/// to be specified when choosing a config (`CGLChoosePixelFormat`).
-/// Therefore, Waffle is constrained by MacOS to require the attributes at
-/// `waffle_config_choose`.
-///
-/// [GLX_ARB_create_context_profile]: http://www.opengl.org/registry/specs/ARB/glx_create_context.txt
-/// [GLX_EXT_create_context_es2_profile]: http://www.opengl.org/registry/specs/EXT/glx_create_context_es2_profile.txt
-/// [EGL 1.4 specification]: http://www.khronos.org/registry/egl/specs/eglspec.1.4.20110406.pdf
-/// [CGL Reference]: https://developer.apple.com/library/mac/#documentation/graphicsimaging/reference/CGL_OpenGL/Reference/reference.html
-///
-///
-/// ##### `WAFFLE_CONTEXT_API` #####
-///
-/// The set of supported values for the `WAFFLE_CONTEXT_API` attribute depends
-/// on the native system.  To check if the system supports a given API, call
-/// waffle_display_supports_context_api().  Invariants and expectations for
-/// each platform are discussed below.
-///
-/// On Android, `WAFFLE_CONTEXT_OPENGL_ES1` is always supported.  If the
-/// Android version is at least 4.0, then `WAFFLE_CONTEXT_OPENGL_ES2` is
-/// supported.  Systems with earlier versions of Android may support
-/// `WAFFLE_CONTEXT_OPENGL_ES2`. No other API is supported.
-///
-/// On GLX, `WAFFLE_CONTEXT_OPENGL` is always supported. The system may
-/// support other APIs.
-///
-/// On X11/EGL and Wayland, no API is guaranteed to be supported. One must
-/// call waffle_display_supports_context_api() to check for supported APIs.
-///
-/// On MacOS, only `WAFFLE_CONTEXT_OPENGL` is supported. This may change in
-/// the future if Apple adds support for additional APIs.
-///
-/// ##### `WAFFLE_CONTEXT_MAJOR_VERSION` and `WAFFLE_CONTEXT_MINOR_VERSION` #####
-///
-/// The default and supported values of the requested context version depend
-/// on the native system and the value of `WAFFLE_CONTEXT_API`.
-///
-/// If the requested API is `WAFFLE_CONTEXT_OPENGL_ES1` then the default and
-/// only supported version is 1.0.  The system may promote the version to 1.1.
-///
-/// If the requested API is `WAFFLE_CONTEXT_OPENGL_ES2`, then the default and
-/// only supported version is 2.0.
-///
-/// For all platforms, if the requested API is `WAFFLE_CONTEXT_OPENGL` then
-/// the default version is 1.0.  If the requested version is less than 3.0
-/// then the native system may promote the requested version to any greater
-/// version that is legacy-compatible.
-///
-/// If the requested API is `WAFFLE_CONTEXT_OPENGL` and the native platform is
-/// MacOS, then the requested version must be 1.0 or 3.2.
-///
-/// If the requested API is `WAFFLE_CONTEXT_OPENGL` and the native platform is
-/// GLX, then the version is unchecked by Waffle and passed directly to GLX at
-/// time of context creation.
-///
-/// If the requested API is `WAFFLE_CONTEXT_OPENGL` and the native platform is
-/// an EGL platform (that is, one of Android, X11/EGL, or Wayland), then the
-/// version must be 1.0. (This restriction may be removed if, in the future,
-/// EGL allows selection of the context version).
-///
-/// ##### `WAFFLE_CONTEXT_PROFILE` #####
-///
-/// The default and supported values for the `WAFFLE_CONTEXT_PROFILE`
-/// attribute depend on the native system and the requested value of
-/// `WAFFLE_CONTEXT_API`.
-///
-/// If the requested API is `WAFFLE_CONTEXT_OPENGL_ES1` or
-/// `WAFFLE_CONTEXT_OPENGL_ES2`, then the default and only supported value is
-/// `WAFFLE_NONE`.
-///
-/// If the requested API is `WAFFLE_CONTEXT_OPENGL`. the the default value is
-/// `WAFFLE_CONTEXT_CORE_PROFILE`. If the requested version is less than 3.2,
-/// then `WAFFLE_CONTEXT_PROFILE` is ignored.
-///
-///
-/// | Name                                    | Type | Default          | Choices                                       |
-/// |:----------------------------------------|-----:|-----------------:|:----------------------------------------------|
-/// | WAFFLE_CONTEXT_API                      | enum |         required | (see discussion)                              |
-/// | .                                       |    . |                . | WAFFLE_CONTEXT_OPENGL                         |
-/// | .                                       |    . |                . | WAFFLE_CONTEXT_OPENGL_ES1                     |
-/// | .                                       |    . |                . | WAFFLE_CONTEXT_OPENGL_ES2                     |
-/// | .                                       |    . |                . | .                                             |
-/// | .                                       |    . |                . | .                                             |
-/// | WAFFLE_CONTEXT_MAJOR_VERSION            |  int | (see discussion) | .                                             |
-/// | WAFFLE_CONTEXT_MINOR_VERSION            |  int | (see discussion) | .                                             |
-/// | .                                       |    . |                . | .                                             |
-/// | WAFFLE_CONTEXT_PROFILE                  | enum | (see discussion) | .                                             |
-/// | .                                       |    . |                . | WAFFLE_NONE                                   |
-/// | .                                       |    . |                . | WAFFLE_CONTEXT_CORE_PROFILE                   |
-/// | .                                       |    . |                . | WAFFLE_CONTEXT_COMPATIBILITY_PROFILE          |
-/// | .                                       |    . |                . | .                                             |
-/// | WAFFLE_RED_SIZE                         |  int | WAFFLE_DONT_CARE | .                                             |
-/// | WAFFLE_GREEN_SIZE                       |  int | WAFFLE_DONT_CARE | .                                             |
-/// | WAFFLE_BLUE_SIZE                        |  int | WAFFLE_DONT_CARE | .                                             |
-/// | WAFFLE_ALPHA_SIZE                       |  int | WAFFLE_DONT_CARE | .                                             |
-/// | .                                       |    . |                . | .                                             |
-/// | WAFFLE_DEPTH_SIZE                       |  int | WAFFLE_DONT_CARE | .                                             |
-/// | WAFFLE_STENCIL_SIZE                     |  int | WAFFLE_DONT_CARE | .                                             |
-/// | .                                       |    . |                . | .                                             |
-/// | WAFFLE_SAMPLE_BUFFERS                   | bool |            false | .                                             |
-/// | WAFFLE_SAMPLES                          |  int |                0 | .                                             |
-/// | .                                       |    . |                . | .                                             |
-/// | WAFFLE_DOUBLE_BUFFERED                  | bool |             true | .                                             |
-/// | WAFFLE_ACCUM_BUFFER                     | bool |            false | .                                             |
-///
 WAFFLE_API struct waffle_config*
 waffle_config_choose(struct waffle_display *dpy, const int32_t attrib_list[]);
 
 WAFFLE_API bool
 waffle_config_destroy(struct waffle_config *self);
 
-/// @brief Get underlying native objects.
-///
-/// Use free() to deallocate the returned pointer.
 WAFFLE_API union waffle_native_config*
 waffle_config_get_native(struct waffle_config *self);
 
 #ifdef __cplusplus
 } // end extern "C"
 #endif
-
-/// @}
diff --git a/include/waffle/waffle_context.h b/include/waffle/waffle_context.h
index a360560..f89da00 100644
--- a/include/waffle/waffle_context.h
+++ b/include/waffle/waffle_context.h
@@ -23,12 +23,6 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-/// @defgroup waffle_context waffle_context
-/// @ingroup waffle_api
-/// @{
-
-/// @file
-
 #pragma once
 
 #include <stdbool.h>
@@ -62,14 +56,9 @@ waffle_context_create(
 WAFFLE_API bool
 waffle_context_destroy(struct waffle_context *self);
 
-/// @brief Get underlying native objects.
-///
-/// Use free() to deallocate the returned pointer.
 WAFFLE_API union waffle_native_context*
 waffle_context_get_native(struct waffle_context *self);
 
 #ifdef __cplusplus
 } // end extern "C"
 #endif
-
-/// @}
diff --git a/include/waffle/waffle_display.h b/include/waffle/waffle_display.h
index d65d269..27e5771 100644
--- a/include/waffle/waffle_display.h
+++ b/include/waffle/waffle_display.h
@@ -23,12 +23,6 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-/// @defgroup waffle_display waffle_display
-/// @ingroup waffle_api
-/// @{
-
-/// @file
-
 #pragma once
 
 #include <stdbool.h>
@@ -57,29 +51,17 @@ union waffle_native_display {
 WAFFLE_API struct waffle_display*
 waffle_display_connect(const char *name);
 
-/// @brief Destructor.
-///
-/// Destroying a display invalidates all pointers to waffle objects that
-/// were created, directly or transitively, from that display.
 WAFFLE_API bool
 waffle_display_disconnect(struct waffle_display *self);
 
-/// Check if the display supports creation of a @ref waffle_context with
-/// the given @a context_api. Choices for @a context_api are
-/// `WAFFLE_CONTEXT_OPENGL*`.
 WAFFLE_API bool
 waffle_display_supports_context_api(
         struct waffle_display *self,
         int32_t context_api);
 
-/// @brief Get underlying native objects.
-///
-/// Use free() to deallocate the returned pointer.
 WAFFLE_API union waffle_native_display*
 waffle_display_get_native(struct waffle_display *self);
 
 #ifdef __cplusplus
 } // end extern "C"
 #endif
-
-/// @}
diff --git a/include/waffle/waffle_dl.h b/include/waffle/waffle_dl.h
index e4cf565..ae7a368 100644
--- a/include/waffle/waffle_dl.h
+++ b/include/waffle/waffle_dl.h
@@ -23,21 +23,6 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-/// @defgroup waffle_dl waffle_dl
-/// @ingroup waffle_api
-///
-/// @brief Dynamic libraries.
-///
-/// Use these functions to query dynamic libraries. For each function, @a dl
-/// must be one of:
-/// - WAFFLE_DL_OPENGL
-/// - WAFFLE_DL_OPENGL_ES1
-/// - WAFFLE_DL_OPENGL_ES2
-///
-/// @{
-
-/// @file
-
 #pragma once
 
 #include <stdbool.h>
@@ -49,16 +34,12 @@
 extern "C" {
 #endif
 
-/// @brief Test if a dynamic library can be opened.
 WAFFLE_API bool
 waffle_dl_can_open(int32_t dl);
 
-/// @brief Get symbol from dynamic library.
 WAFFLE_API void*
 waffle_dl_sym(int32_t dl, const char *name);
 
 #ifdef __cplusplus
 } // end extern "C"
 #endif
-
-/// @}
diff --git a/include/waffle/waffle_enum.h b/include/waffle/waffle_enum.h
index ffcc42f..df87e0e 100644
--- a/include/waffle/waffle_enum.h
+++ b/include/waffle/waffle_enum.h
@@ -23,12 +23,6 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-/// @defgroup waffle_enum waffle_enum
-/// @ingroup waffle_api
-/// @{
-
-/// @file
-
 #pragma once
 
 #include <stddef.h>
@@ -40,18 +34,9 @@
 extern "C" {
 #endif
 
-/// @brief Convert a waffle_enum to a string.
-///
-/// For example, convert @c WAFFLE_OPENGL to @c "WAFFLE_OPENGL" .
-///
-/// @return null if enum is invalid.
 WAFFLE_API const char*
 waffle_enum_to_string(int32_t e);
 
-/// @brief All non-error enums used by waffle.
-///
-/// All enums are placed in one list so that each has a distinct value. This
-/// enables better error detection at API entry points.
 enum waffle_enum {
     // ------------------------------------------------------------------
     // Generic
@@ -115,5 +100,3 @@ enum waffle_enum {
 #ifdef __cplusplus
 } // end extern "C"
 #endif
-
-/// @}
diff --git a/include/waffle/waffle_error.h b/include/waffle/waffle_error.h
index 6e0af70..af9497c 100644
--- a/include/waffle/waffle_error.h
+++ b/include/waffle/waffle_error.h
@@ -23,13 +23,6 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-/// @defgroup waffle_error waffle_error
-/// @ingroup waffle_api
-///
-/// @{
-
-/// @file
-
 #pragma once
 
 #include <stdint.h>
@@ -41,111 +34,36 @@
 extern "C" {
 #endif
 
-/// @brief Thread-local error info.
-///
-/// Waffle functions usually return either a bool, in which false indicates
-/// failure, or a pointer, in which null indicates failure. In addition to
-/// returning a flag indicating failure, most functions also clear and then
-/// set some thread-local error state. The only functions that do not alter
-/// the error state are those in this module, @ref waffle_error.
-///
-/// This struct contains the user-visible portion of the thread-local
-/// error state.
 struct waffle_error_info {
-    /// @brief An error code from `enum waffle_error`.
-    ///
-    /// This may be `WAFFLE_NO_ERROR`.
     int32_t code;
-
-    /// Never null.
     const char *message;
-
-    /// @brief The length of @ref message according to strlen().
     size_t message_length;
 };
 
-/// @brief Get the current thread's error code.
-///
-/// Calling this function is equivalent to obtaining the error code with
-/// `waffle_error_get_info()->code`.
-///
 WAFFLE_API int32_t
 waffle_error_get_code(void);
 
-/// @brief Get the current thread's error info.
-///
-/// This function never returns null. The returned pointer becomes invalid
-/// when the thread-local error state changes.
-///
-/// This may be called when waffle is uninitialized [that is, before
-/// waffle_init()].
 WAFFLE_API const struct waffle_error_info*
 waffle_error_get_info(void);
 
-/// @brief Convert error code to string.
-///
-/// For example, convert @c WAFFLE_BAD_ATTRIBUTE to @c "WAFFLE_BAD_ATTRIBUTE" .
-///
-/// @return null if enum is invalid.
 WAFFLE_API const char*
 waffle_error_to_string(int32_t e);
 
 enum waffle_error {
-    /// The function succeeded.
     WAFFLE_NO_ERROR                     = 0x00,
-
-    /// Waffle encountered a fatal error.  All future Waffle calls result in
-    /// undefined behavior.
     WAFFLE_ERROR_FATAL                  = 0x01,
-
-    /// Waffle encountered an error for which it lacks an error code.  This is
-    /// usually produced when an underlying native call, such as
-    /// XOpenDisplay(), fails for an unknown reason.
     WAFFLE_ERROR_UNKNOWN                = 0x02,
-
-    /// You found a bug in Waffle.  Please report it.  The error message,
-    /// obtained by waffle_error_get_info(), should contain a description of
-    /// the bug.
     WAFFLE_ERROR_INTERNAL               = 0x03,
-
-    /// Waffle failed to allocate memory.
     WAFFLE_ERROR_BAD_ALLOC              = 0x04,
-
-    /// The failed function requires Waffle to be initialized with
-    /// waffle_init().
     WAFFLE_ERROR_NOT_INITIALIZED        = 0x05,
-
-    /// If Waffle has already been initialized by a successful call to
-    /// waffle_init(), then subsequent calls to waffle_init() produce this
-    /// error.
     WAFFLE_ERROR_ALREADY_INITIALIZED    = 0x06,
-
-    /// An unrecognized attribute name or attribute value was passed in an
-    /// attribute list.
     WAFFLE_ERROR_BAD_ATTRIBUTE          = 0x08,
-
-    /// The failed function was passed an invalid argument.
     WAFFLE_ERROR_BAD_PARAMETER          = 0x10,
-
-    /// The Waffle objects passed to the failed function belong to different
-    /// displays.
     WAFFLE_ERROR_BAD_DISPLAY_MATCH      = 0x11,
-
-    /// The requested action is unsupported on the current system or platform,
-    /// but is otherwise valid.  For example, the following produce this
-    /// error:
-    ///     - Attemtping to choose a waffle_config whose API is OpenGL ES1
-    ///       when the current platform is GLX.
-    ///     - Calling `waffle_dl_sym(WAFFLE_DL_OPENGL_ES2, ...)` when the
-    ///       OpenGL ES2 library is not present on the system.
     WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM = 0x12,
-
-    /// Waffle was built without support for the requested action.
     WAFFLE_ERROR_BUILT_WITHOUT_SUPPORT   = 0x13,
 };
 
 #ifdef __cplusplus
 } // end extern "C"
 #endif
-
-/// @}
diff --git a/include/waffle/waffle_gl_misc.h b/include/waffle/waffle_gl_misc.h
index dd7ef3a..71139f2 100644
--- a/include/waffle/waffle_gl_misc.h
+++ b/include/waffle/waffle_gl_misc.h
@@ -23,12 +23,6 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-/// @defgroup waffle_gl_misc waffle_gl_misc
-/// @ingroup waffle_api
-/// @{
-
-/// @file
-
 #pragma once
 
 #include <stdbool.h>
@@ -44,32 +38,20 @@ struct waffle_context;
 struct waffle_display;
 struct waffle_window;
 
-/// @brief Check if an extension is contained in a GL-style extension string.
-///
-/// The @a extension_string must be in the format returned by
-/// `glGetString(GL_EXTENSIONS)`. Note that this function is not restricted to
-/// the GL extension string; it can also be used on the GLX and EGL extension
-/// strings.
-///
-/// This function may be called before waffle_init().
 WAFFLE_API bool
 waffle_is_extension_in_string(
         const char *restrict extension_string,
         const char *restrict extension_name);
 
-/// @brief Analogous to eglMakeCurrent.
 WAFFLE_API bool
 waffle_make_current(
         struct waffle_display *dpy,
         struct waffle_window *window,
         struct waffle_context *ctx);
 
-/// @brief Analogous to eglGetProcAddress.
 WAFFLE_API void*
 waffle_get_proc_address(const char *name);
 
 #ifdef __cplusplus
 } // end extern "C"
 #endif
-
-/// @}
diff --git a/include/waffle/waffle_init.h b/include/waffle/waffle_init.h
index c039114..7a71635 100644
--- a/include/waffle/waffle_init.h
+++ b/include/waffle/waffle_init.h
@@ -23,12 +23,6 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-/// @defgroup waffle_init waffle_init
-/// @ingroup waffle_api
-///
-/// @brief Initializing and terminating global library state.
-/// @{
-
 #pragma once
 
 #include <stdbool.h>
@@ -40,58 +34,9 @@
 extern "C" {
 #endif
 
-/// @brief Initialize the per-process global state of the waffle library.
-///
-/// This function must be called before calling any other waffle functions
-/// If waffle is already initialized, then calling waffle_init() produces the
-/// error @c WAFFLE_ERROR_ALREADY_INITIALIZED.
-///
-///
-/// ### Attributes ###
-///
-/// Argument @a attrib_list specifies a list of attributes, described in the
-/// table below, with which to initialize the waffle library. The list consists
-/// of a zero-terminated sequence of name/value pairs. If an attribute is
-/// absent from the list, then the attribute assumes its default value. If @a
-/// attrib_list is null or empty, then all attributes assume their default
-/// values.
-///
-/// |Name                                    | Required | Type | Default | Choices                      |
-/// |:---------------------------------------|:--------:|-----:|--------:|:-----------------------------|
-/// | WAFFLE_PLATFORM                        |   yes    | enum |    none | WAFFLE_PLATFORM_ANDROID      |
-/// | .                                      |     .    |    . |       . | WAFFLE_PLATFORM_CGL          |
-/// | .                                      |     .    |    . |       . | WAFFLE_PLATFORM_GLX          |
-/// | .                                      |     .    |    . |       . | WAFFLE_PLATFORM_WAYLAND      |
-/// | .                                      |     .    |    . |       . | WAFFLE_PLATFORM_X11_EGL      |
-///
-///
-/// ### Example Attribute Lists ###
-///
-/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
-/// const int32_t attrib_list[] = {
-///   WAFFLE_PLATFORM,      WAFFLE_PLATFORM_ANDROID,
-///   0,
-/// }
-/// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-///
-///
-/// ### Errors ###
-///
-/// - WAFFLE_ERROR_ALREADY_INITIALIZED @n
-///     The library's global state has already been initialized with a call
-///     to waffle_init().
-///
-/// - WAFFLE_ERROR_BAD_ATTRIBUTE @n
-///     An item in @a attrib_list is unrecognized, missing, or has an
-///     invalid value.
-///
-/// @see waffle_enum
-///
 WAFFLE_API bool
 waffle_init(const int32_t *attrib_list);
 
 #ifdef __cplusplus
 } // end extern "C"
 #endif
-
-/// @}
diff --git a/include/waffle/waffle_window.h b/include/waffle/waffle_window.h
index 02da0f4..9f43df4 100644
--- a/include/waffle/waffle_window.h
+++ b/include/waffle/waffle_window.h
@@ -23,10 +23,6 @@
 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-/// @defgroup waffle_window waffle_window
-/// @ingroup waffle_api
-/// @{
-
 #pragma once
 
 #include <stdbool.h>
@@ -53,8 +49,6 @@ union waffle_native_window {
     struct waffle_wayland_window *wayland;
 };
 
-/// If the platform allows, the window is not displayed onto the screen
-/// after creation. To display the window, call waffle_window_show().
 WAFFLE_API struct waffle_window*
 waffle_window_create(
         struct waffle_config *config,
@@ -64,24 +58,15 @@ waffle_window_create(
 WAFFLE_API bool
 waffle_window_destroy(struct waffle_window *self);
 
-/// @brief Show the window on the screen.
-///
-/// If the window is already shown, this does nothing.
 WAFFLE_API bool
 waffle_window_show(struct waffle_window *self);
 
-/// @brief Analogous to eglSwapBuffers.
 WAFFLE_API bool
 waffle_window_swap_buffers(struct waffle_window *self);
 
-/// @brief Get underlying native objects.
-///
-/// Use free() to deallocate the returned pointer.
 WAFFLE_API union waffle_native_window*
 waffle_window_get_native(struct waffle_window *self);
 
 #ifdef __cplusplus
 } // end extern "C"
 #endif
-
-/// @}