Reorganize documentation

2 files changed, 180 insertions, 129 deletions

diff --git a/doc/c/Doxyfile.in b/doc/c/Doxyfile.in
index d119015..f0b8236 100644
--- a/doc/c/Doxyfile.in
+++ b/doc/c/Doxyfile.in
@@ -21,12 +21,19 @@ SHOW_FILES             = NO
 
 MACRO_EXPANSION        = YES
 PREDEFINED             = PUGL_API \
-                         PUGL_DISABLE_DEPRECATED \
                          PUGL_CONST_API= \
-                         PUGL_CONST_FUNC=
+                         PUGL_CONST_FUNC= \
+                         PUGL_DISABLE_DEPRECATED \
+                         PUGL_MALLOC_API= \
+                         PUGL_MALLOC_FUNC=
 
 RECURSIVE              = YES
 STRIP_FROM_PATH        = @PUGL_SRCDIR@
-INPUT                  = @PUGL_SRCDIR@/include
+INPUT                  = @PUGL_SRCDIR@/include/pugl/attributes.h \
+                         @PUGL_SRCDIR@/include/pugl/pugl.h \
+                         @PUGL_SRCDIR@/include/pugl/cairo.h \
+                         @PUGL_SRCDIR@/include/pugl/gl.h \
+                         @PUGL_SRCDIR@/include/pugl/stub.h \
+                         @PUGL_SRCDIR@/include/pugl/vulkan.h
 
 OUTPUT_DIRECTORY       = @DOX_OUTPUT@
diff --git a/include/pugl/pugl.h b/include/pugl/pugl.h
index 981d76d..637460e 100644
--- a/include/pugl/pugl.h
+++ b/include/pugl/pugl.h
@@ -22,6 +22,11 @@ PUGL_BEGIN_DECLS
 */
 
 /**
+   @defgroup geometry_types Geometry Types
+   @{
+*/
+
+/**
    A pixel coordinate within/of a view.
 
    This is relative to the top left corner of the view's parent, or to the top
@@ -59,89 +64,16 @@ typedef struct {
 } PuglRect;
 
 /**
+   @}
    @defgroup events Events
 
    All updates to the view happen via events, which are dispatched to the
-   view's event function.  Most events map directly to one from the underlying
-   window system, but some are constructed by Pugl itself so there is not
-   necessarily a direct correspondence.
+   view's event function.  An event is a tagged union with a type, and a set of
+   more specific fields depending on the type.
 
    @{
 */
 
-/// Keyboard modifier flags
-typedef enum {
-  PUGL_MOD_SHIFT = 1U << 0U, ///< Shift key
-  PUGL_MOD_CTRL  = 1U << 1U, ///< Control key
-  PUGL_MOD_ALT   = 1U << 2U, ///< Alt/Option key
-  PUGL_MOD_SUPER = 1U << 3U  ///< Mod4/Command/Windows key
-} PuglMod;
-
-/// Bitwise OR of #PuglMod values
-typedef uint32_t PuglMods;
-
-/**
-   Keyboard key codepoints.
-
-   All keys are identified by a Unicode code point in PuglKeyEvent::key.  This
-   enumeration defines constants for special keys that do not have a standard
-   code point, and some convenience constants for control characters.  Note
-   that all keys are handled in the same way, this enumeration is just for
-   convenience when writing hard-coded key bindings.
-
-   Keys that do not have a standard code point use values in the Private Use
-   Area in the Basic Multilingual Plane (`U+E000` to `U+F8FF`).  Applications
-   must take care to not interpret these values beyond key detection, the
-   mapping used here is arbitrary and specific to Pugl.
-*/
-typedef enum {
-  // ASCII control codes
-  PUGL_KEY_BACKSPACE = 0x08,
-  PUGL_KEY_ESCAPE    = 0x1B,
-  PUGL_KEY_DELETE    = 0x7F,
-
-  // Unicode Private Use Area
-  PUGL_KEY_F1 = 0xE000,
-  PUGL_KEY_F2,
-  PUGL_KEY_F3,
-  PUGL_KEY_F4,
-  PUGL_KEY_F5,
-  PUGL_KEY_F6,
-  PUGL_KEY_F7,
-  PUGL_KEY_F8,
-  PUGL_KEY_F9,
-  PUGL_KEY_F10,
-  PUGL_KEY_F11,
-  PUGL_KEY_F12,
-  PUGL_KEY_LEFT,
-  PUGL_KEY_UP,
-  PUGL_KEY_RIGHT,
-  PUGL_KEY_DOWN,
-  PUGL_KEY_PAGE_UP,
-  PUGL_KEY_PAGE_DOWN,
-  PUGL_KEY_HOME,
-  PUGL_KEY_END,
-  PUGL_KEY_INSERT,
-  PUGL_KEY_SHIFT,
-  PUGL_KEY_SHIFT_L = PUGL_KEY_SHIFT,
-  PUGL_KEY_SHIFT_R,
-  PUGL_KEY_CTRL,
-  PUGL_KEY_CTRL_L = PUGL_KEY_CTRL,
-  PUGL_KEY_CTRL_R,
-  PUGL_KEY_ALT,
-  PUGL_KEY_ALT_L = PUGL_KEY_ALT,
-  PUGL_KEY_ALT_R,
-  PUGL_KEY_SUPER,
-  PUGL_KEY_SUPER_L = PUGL_KEY_SUPER,
-  PUGL_KEY_SUPER_R,
-  PUGL_KEY_MENU,
-  PUGL_KEY_CAPS_LOCK,
-  PUGL_KEY_SCROLL_LOCK,
-  PUGL_KEY_NUM_LOCK,
-  PUGL_KEY_PRINT_SCREEN,
-  PUGL_KEY_PAUSE
-} PuglKey;
-
 /// The type of a PuglEvent
 typedef enum {
   PUGL_NOTHING,        ///< No event
@@ -188,22 +120,6 @@ typedef enum {
   PUGL_CROSSING_UNGRAB  ///< Crossing due to a grab release
 } PuglCrossingMode;
 
-/**
-   Scroll direction.
-
-   Describes the direction of a #PuglScrollEvent along with whether the scroll
-   is a "smooth" scroll.  The discrete directions are for devices like mouse
-   wheels with constrained axes, while a smooth scroll is for those with
-   arbitrary scroll direction freedom, like some touchpads.
-*/
-typedef enum {
-  PUGL_SCROLL_UP,    ///< Scroll up
-  PUGL_SCROLL_DOWN,  ///< Scroll down
-  PUGL_SCROLL_LEFT,  ///< Scroll left
-  PUGL_SCROLL_RIGHT, ///< Scroll right
-  PUGL_SCROLL_SMOOTH ///< Smooth scroll in any direction
-} PuglScrollDirection;
-
 /// Common header for all event structs
 typedef struct {
   PuglEventType  type;  ///< Event type
@@ -211,6 +127,11 @@ typedef struct {
 } PuglAnyEvent;
 
 /**
+   @defgroup management_events Management Events
+   @{
+*/
+
+/**
    View create event.
 
    This event is sent when a view is realized before it is first displayed,
@@ -273,6 +194,54 @@ typedef PuglAnyEvent PuglMapEvent;
 typedef PuglAnyEvent PuglUnmapEvent;
 
 /**
+   Recursive loop enter event.
+
+   This event is sent when the window system enters a recursive loop.  The main
+   loop will be stalled and no expose events will be received while in the
+   recursive loop.  To give the application full control, Pugl does not do any
+   special handling of this situation, but this event can be used to install a
+   timer to perform continuous actions (such as drawing) on platforms that do
+   this.
+
+   - MacOS: A recursive loop is entered while the window is being live resized.
+
+   - Windows: A recursive loop is entered while the window is being live
+     resized or the menu is shown.
+
+   - X11: A recursive loop is never entered and the event loop runs as usual
+     while the view is being resized.
+
+   This event type has no extra fields.
+*/
+typedef PuglAnyEvent PuglLoopEnterEvent;
+
+/**
+   Recursive loop leave event.
+
+   This event is sent after a loop enter event when the recursive loop is
+   finished and normal iteration will continue.
+
+   This event type has no extra fields.
+*/
+typedef PuglAnyEvent PuglLoopLeaveEvent;
+
+/**
+   View close event.
+
+   This event is sent when the view is to be closed, for example when the user
+   clicks the close button.
+
+   This event type has no extra fields.
+*/
+typedef PuglAnyEvent PuglCloseEvent;
+
+/**
+   @}
+   @defgroup update_events Update Events
+   @{
+*/
+
+/**
    View update event.
 
    This event is sent to every view near the end of a main loop iteration when
@@ -300,14 +269,83 @@ typedef struct {
 } PuglExposeEvent;
 
 /**
-   View close event.
+   @}
+   @defgroup keyboard_events Keyboard Events
+   @{
+*/
 
-   This event is sent when the view is to be closed, for example when the user
-   clicks the close button.
+/**
+   Keyboard key codepoints.
 
-   This event type has no extra fields.
+   All keys are identified by a Unicode code point in PuglKeyEvent::key.  This
+   enumeration defines constants for special keys that do not have a standard
+   code point, and some convenience constants for control characters.  Note
+   that all keys are handled in the same way, this enumeration is just for
+   convenience when writing hard-coded key bindings.
+
+   Keys that do not have a standard code point use values in the Private Use
+   Area in the Basic Multilingual Plane (`U+E000` to `U+F8FF`).  Applications
+   must take care to not interpret these values beyond key detection, the
+   mapping used here is arbitrary and specific to Pugl.
 */
-typedef PuglAnyEvent PuglCloseEvent;
+typedef enum {
+  // ASCII control codes
+  PUGL_KEY_BACKSPACE = 0x08,
+  PUGL_KEY_ESCAPE    = 0x1B,
+  PUGL_KEY_DELETE    = 0x7F,
+
+  // Unicode Private Use Area
+  PUGL_KEY_F1 = 0xE000,
+  PUGL_KEY_F2,
+  PUGL_KEY_F3,
+  PUGL_KEY_F4,
+  PUGL_KEY_F5,
+  PUGL_KEY_F6,
+  PUGL_KEY_F7,
+  PUGL_KEY_F8,
+  PUGL_KEY_F9,
+  PUGL_KEY_F10,
+  PUGL_KEY_F11,
+  PUGL_KEY_F12,
+  PUGL_KEY_LEFT,
+  PUGL_KEY_UP,
+  PUGL_KEY_RIGHT,
+  PUGL_KEY_DOWN,
+  PUGL_KEY_PAGE_UP,
+  PUGL_KEY_PAGE_DOWN,
+  PUGL_KEY_HOME,
+  PUGL_KEY_END,
+  PUGL_KEY_INSERT,
+  PUGL_KEY_SHIFT,
+  PUGL_KEY_SHIFT_L = PUGL_KEY_SHIFT,
+  PUGL_KEY_SHIFT_R,
+  PUGL_KEY_CTRL,
+  PUGL_KEY_CTRL_L = PUGL_KEY_CTRL,
+  PUGL_KEY_CTRL_R,
+  PUGL_KEY_ALT,
+  PUGL_KEY_ALT_L = PUGL_KEY_ALT,
+  PUGL_KEY_ALT_R,
+  PUGL_KEY_SUPER,
+  PUGL_KEY_SUPER_L = PUGL_KEY_SUPER,
+  PUGL_KEY_SUPER_R,
+  PUGL_KEY_MENU,
+  PUGL_KEY_CAPS_LOCK,
+  PUGL_KEY_SCROLL_LOCK,
+  PUGL_KEY_NUM_LOCK,
+  PUGL_KEY_PRINT_SCREEN,
+  PUGL_KEY_PAUSE
+} PuglKey;
+
+/// Keyboard modifier flags
+typedef enum {
+  PUGL_MOD_SHIFT = 1U << 0U, ///< Shift key
+  PUGL_MOD_CTRL  = 1U << 1U, ///< Control key
+  PUGL_MOD_ALT   = 1U << 2U, ///< Alt/Option key
+  PUGL_MOD_SUPER = 1U << 3U  ///< Mod4/Command/Windows key
+} PuglMod;
+
+/// Bitwise OR of #PuglMod values
+typedef uint32_t PuglMods;
 
 /**
    Keyboard focus event.
@@ -377,6 +415,28 @@ typedef struct {
 } PuglTextEvent;
 
 /**
+   @}
+   @defgroup pointer_events Pointer Events
+   @{
+*/
+
+/**
+   Scroll direction.
+
+   Describes the direction of a #PuglScrollEvent along with whether the scroll
+   is a "smooth" scroll.  The discrete directions are for devices like mouse
+   wheels with constrained axes, while a smooth scroll is for those with
+   arbitrary scroll direction freedom, like some touchpads.
+*/
+typedef enum {
+  PUGL_SCROLL_UP,    ///< Scroll up
+  PUGL_SCROLL_DOWN,  ///< Scroll down
+  PUGL_SCROLL_LEFT,  ///< Scroll left
+  PUGL_SCROLL_RIGHT, ///< Scroll right
+  PUGL_SCROLL_SMOOTH ///< Smooth scroll in any direction
+} PuglScrollDirection;
+
+/**
    Pointer enter or leave event.
 
    This event is sent when the pointer enters or leaves the view.  This can
@@ -463,6 +523,12 @@ typedef struct {
 } PuglScrollEvent;
 
 /**
+   @}
+   @defgroup custom_events Custom Events
+   @{
+*/
+
+/**
    Custom client message event.
 
    This can be used to send a custom message to a view, which is delivered via
@@ -493,6 +559,12 @@ typedef struct {
 } PuglTimerEvent;
 
 /**
+   @}
+   @defgroup clipboard_events Clipboard Events
+   @{
+*/
+
+/**
    Clipboard data offer event.
 
    This event is sent when a clipboard has data present, possibly with several
@@ -521,36 +593,8 @@ typedef struct {
 } PuglDataEvent;
 
 /**
-   Recursive loop enter event.
-
-   This event is sent when the window system enters a recursive loop.  The main
-   loop will be stalled and no expose events will be received while in the
-   recursive loop.  To give the application full control, Pugl does not do any
-   special handling of this situation, but this event can be used to install a
-   timer to perform continuous actions (such as drawing) on platforms that do
-   this.
-
-   - MacOS: A recursive loop is entered while the window is being live resized.
-
-   - Windows: A recursive loop is entered while the window is being live
-     resized or the menu is shown.
-
-   - X11: A recursive loop is never entered and the event loop runs as usual
-     while the view is being resized.
-
-   This event type has no extra fields.
-*/
-typedef PuglAnyEvent PuglLoopEnterEvent;
-
-/**
-   Recursive loop leave event.
-
-   This event is sent after a loop enter event when the recursive loop is
-   finished and normal iteration will continue.
-
-   This event type has no extra fields.
+   @}
 */
-typedef PuglAnyEvent PuglLoopLeaveEvent;
 
 /**
    View event.