Organize documentation into groups

5 files changed, 58 insertions, 14 deletions

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.
    @{
 */
 
@@ -72,6 +72,19 @@ typedef struct {
 } 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.
 */
 typedef enum {
@@ -405,6 +418,15 @@ typedef union {
 } PuglEvent;
 
 /**
+   @}
+   @defgroup status Status
+
+   Status codes and error handling.
+
+   @{
+*/
+
+/**
    Return status code.
 */
 typedef enum {
@@ -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.
 
@@ -612,6 +634,12 @@ typedef enum {
 typedef PuglStatus (*PuglEventFunc)(PuglView* view, const PuglEvent* event);
 
 /**
+   @name Setup
+   Functions for creating and destroying a view.
+   @{
+*/
+
+/**
    Create a new view.
 
    A newly created view does not correspond to a real system view or window.
@@ -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
    @{
 */