From 0a4e6e1568e2369d80ed7ac9af4751dc2a276364 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Sat, 7 Mar 2020 18:27:44 +0100
Subject: Organize documentation into groups

---
 pugl/pugl.h       | 50 +++++++++++++++++++++++++++++++++++++++++---------
 pugl/pugl.hpp     | 16 ++++++++++++++--
 pugl/pugl_cairo.h |  2 +-
 pugl/pugl_gl.h    |  2 +-
 pugl/pugl_stub.h  |  2 +-
 5 files changed, 58 insertions(+), 14 deletions(-)

(limited to 'pugl')

diff --git a/pugl/pugl.h b/pugl/pugl.h
index 3b156ed..c5261a8 100644
--- a/pugl/pugl.h
+++ b/pugl/pugl.h
@@ -15,7 +15,7 @@
 */
 
 /**
-   @file pugl.h Public C API.
+   @file pugl.h Pugl API.
 */
 
 #ifndef PUGL_PUGL_H
@@ -53,8 +53,8 @@
 PUGL_BEGIN_DECLS
 
 /**
-   @defgroup pugl Pugl
-   Pugl C API.
+   @defgroup pugl_api Pugl
+   A minimal portable API for embeddable GUIs.
    @{
 */
 
@@ -71,6 +71,19 @@ typedef struct {
 	double height;
 } PuglRect;
 
+/**
+   @defgroup events Events
+
+   Event definitions.
+
+   All updates to the view happen via events, which are dispatched to the
+   view's #PuglEventFunc by Pugl.  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.
+
+   @{
+*/
+
 /**
    Keyboard modifier flags.
 */
@@ -404,6 +417,15 @@ typedef union {
 	PuglEventFocus     focus;     ///< #PUGL_FOCUS_IN, #PUGL_FOCUS_OUT
 } PuglEvent;
 
+/**
+   @}
+   @defgroup status Status
+
+   Status codes and error handling.
+
+   @{
+*/
+
 /**
    Return status code.
 */
@@ -428,8 +450,8 @@ const char*
 puglStrerror(PuglStatus status);
 
 /**
-   @anchor world
-   @name World
+   @}
+   @defgroup world World
 
    The top-level context of a Pugl application or plugin.
 
@@ -527,8 +549,8 @@ puglDispatchEvents(PuglWorld* world);
 
 /**
    @}
-   @anchor view
-   @name View
+
+   @defgroup view View
 
    A drawable region that receives events.
 
@@ -611,6 +633,12 @@ typedef enum {
 */
 typedef PuglStatus (*PuglEventFunc)(PuglView* view, const PuglEvent* event);
 
+/**
+   @name Setup
+   Functions for creating and destroying a view.
+   @{
+*/
+
 /**
    Create a new view.
 
@@ -807,8 +835,8 @@ puglGetNativeWindow(PuglView* view);
 
 /**
    @}
-   @name Graphics Context
-   Functions for working with the drawing context.
+   @name Graphics
+   Functions for working with the graphics context and scheduling redisplays.
    @{
 */
 
@@ -937,6 +965,10 @@ puglGetClipboard(PuglView* view, const char** type, size_t* len);
 PUGL_API PuglStatus
 puglRequestAttention(PuglView* view);
 
+/**
+   @}
+*/
+
 #ifndef PUGL_DISABLE_DEPRECATED
 
 /**
diff --git a/pugl/pugl.hpp b/pugl/pugl.hpp
index 1c4b9e7..73cfe2a 100644
--- a/pugl/pugl.hpp
+++ b/pugl/pugl.hpp
@@ -25,13 +25,25 @@
 
 /**
    @defgroup puglxx C++
-   Pugl C++ API wrapper.
-   @ingroup pugl
+
+   C++ API wrapper.
+
+   @ingroup pugl_api
    @{
 */
 
+/**
+   Pugl C++ API namespace.
+*/
 namespace pugl {
 
+/**
+   A drawable region that receives events.
+
+   This is a thin wrapper for a PuglView that contains only a pointer.
+
+   @ingroup puglxx
+*/
 class View {
 public:
 	View(int* pargc, char** argv)
diff --git a/pugl/pugl_cairo.h b/pugl/pugl_cairo.h
index c289c16..e71072e 100644
--- a/pugl/pugl_cairo.h
+++ b/pugl/pugl_cairo.h
@@ -28,7 +28,7 @@ PUGL_BEGIN_DECLS
 /**
    @defgroup cairo Cairo
    Cairo graphics support.
-   @ingroup pugl
+   @ingroup pugl_api
    @{
 */
 
diff --git a/pugl/pugl_gl.h b/pugl/pugl_gl.h
index eb2b16f..9c5fa94 100644
--- a/pugl/pugl_gl.h
+++ b/pugl/pugl_gl.h
@@ -28,7 +28,7 @@ PUGL_BEGIN_DECLS
 /**
    @defgroup gl OpenGL
    OpenGL graphics support.
-   @ingroup pugl
+   @ingroup pugl_api
    @{
 */
 
diff --git a/pugl/pugl_stub.h b/pugl/pugl_stub.h
index a99eb4a..295f4f9 100644
--- a/pugl/pugl_stub.h
+++ b/pugl/pugl_stub.h
@@ -36,7 +36,7 @@ PUGL_BEGIN_DECLS
    for other backends to reuse since not all need non-trivial implementations
    of every backend function.
 
-   @ingroup pugl
+   @ingroup pugl_api
    @{
 */
 
-- 
cgit v1.2.1