Simplify documentation structure

6 files changed, 43 insertions, 61 deletions

diff --git a/doc/mainpage.md b/doc/mainpage.md
index c04bf9e..3dd4511 100644
--- a/doc/mainpage.md
+++ b/doc/mainpage.md
@@ -1,23 +1,29 @@
-This is the API documentation for Pugl.
-This page refers to the [C API](@ref pugl_c),
-there is also a [C++ API](@ref pugl_cxx) in the `pugl` namespace.
+This is the documentation for Pugl, a minimal API for writing GUIs.
 
-The Pugl API revolves around two main objects:
-the [World](@ref world) and the [View](@ref view).
+## Reference
+
+Pugl is implemented in C, but also provides a header-only C++ API wrapper.
+
+ * [C API reference](@ref pugl_c)
+ * [C++ API reference](@ref pugl_cxx)
+
+## Overview
+
+The Pugl API revolves around two main objects: the World and the View.
 An application creates a single world to manage top-level state,
 then creates one or more views to display.
 
-## World
+### World
 
-The [World](@ref world) contains all top-level state,
+The [World](@ref PuglWorld) contains all top-level state,
 and manages views and the event loop.
 
 A world must be [created](@ref puglNewWorld) before any views,
 and it must outlive all views.
 
-## View
+### View
 
-A [View](@ref view) is a drawable region that receives events.
+A [View](@ref PuglView) is a drawable region that receives events.
 
 Creating a visible view is a multi-step process.
 When a new view is [created](@ref puglNewView),
@@ -29,8 +35,7 @@ and optionally [adjusting the frame](@ref frame).
 
 The [Backend](@ref PuglBackend) controls drawing for a view.
 Pugl includes [Cairo](@ref cairo) and [OpenGL](@ref gl) backends,
-as well as a [stub](@ref stub) backend that creates a native window with no drawing context.
-
+as well as a [stub](@ref stub) backend that creates a native window with no portable drawing context.
 
 Once the view is configured,
 it can be [realized](@ref puglRealize) and [shown](@ref puglShowWindow).
@@ -38,17 +43,16 @@ By default a view will correspond to a top-level system window.
 To create a view within another window,
 it must have a [parent window set](@ref puglSetParentWindow) before being created.
 
+### Events
 
-## Events
-
-[Events](@ref events) are sent to a view when it has received user input or must be drawn.
+[Events](@ref PuglEvent) are sent to a view when it has received user input or must be drawn.
 
 Events are handled by the [event handler](@ref PuglEventFunc) set during initialisation.
 This function is called whenever something happens that the view must respond to.
 This includes user interaction like mouse and keyboard input,
 and system events like window resizing and exposure.
 
-## Event Loop
+### Event Loop
 
 The event loop is driven by repeatedly calling #puglUpdate which processes events from the window system,
 and dispatches them to views when necessary.
@@ -68,6 +72,6 @@ For continuous redrawing, call #puglPostRedisplay when a #PUGL_UPDATE event is r
 This event is sent before views are redrawn,
 so can be used as a hook to expand the update region right before the view is exposed.
 
-## Error Handling
+### Error Handling
 
-Most functions return a [Status](@ref status) which should be checked to detect failure.
+Most functions return a [Status](@ref PuglStatus) which should be checked to detect failure.
diff --git a/include/pugl/pugl.h b/include/pugl/pugl.h
index bad881f..13c0b22 100644
--- a/include/pugl/pugl.h
+++ b/include/pugl/pugl.h
@@ -93,14 +93,12 @@ typedef struct {
 } PuglRect;
 
 /**
-   @defgroup events Events
-
-   Event definitions.
+   @name Events
 
    All updates to the view happen via events, which are dispatched to the
-   view's event function 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.
+   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.
 
    @{
 */
@@ -559,9 +557,9 @@ typedef union {
 
 /**
    @}
-   @defgroup status Status
+   @name Status
 
-   Status codes and error handling.
+   Most functions return a status code which can be used to check for errors.
 
    @{
 */
@@ -593,7 +591,7 @@ puglStrerror(PuglStatus status);
 
 /**
    @}
-   @defgroup world World
+   @name World
 
    The top-level context of a Pugl application or plugin.
 
@@ -777,8 +775,7 @@ puglUpdate(PuglWorld* world, double timeout);
 
 /**
    @}
-
-   @defgroup view View
+   @name View
 
    A drawable region that receives events.
 
diff --git a/include/pugl/pugl.hpp b/include/pugl/pugl.hpp
index 8fc479f..d9e725a 100644
--- a/include/pugl/pugl.hpp
+++ b/include/pugl/pugl.hpp
@@ -32,6 +32,11 @@
 #include <type_traits>
 
 /**
+   Pugl C++ API namespace.
+*/
+namespace pugl {
+
+/**
    @defgroup pugl_cxx C++ API
    C++ API wrapper.
 
@@ -39,11 +44,6 @@
    @{
 */
 
-/**
-   Pugl C++ API namespace.
-*/
-namespace pugl {
-
 namespace detail {
 
 /// Free function for a C object
@@ -84,9 +84,7 @@ private:
 using Rect = PuglRect; ///< @copydoc PuglRect
 
 /**
-   @defgroup eventsxx Events
-   @ingroup pugl_cxx
-   @copydoc events
+   @name Events
    @{
 */
 
@@ -180,9 +178,7 @@ using TimerEvent = Event<PUGL_TIMER, PuglEventTimer>;
 
 /**
    @}
-   @defgroup statusxx Status
-   @ingroup pugl_cxx
-   @copydoc status
+   @name Status
    @{
 */
 
@@ -213,9 +209,7 @@ strerror(const pugl::Status status)
 
 /**
    @}
-   @defgroup worldxx World
-   @ingroup pugl_cxx
-   @copydoc world
+   @name World
    @{
 */
 
@@ -350,9 +344,7 @@ Clock::now() const
 
 /**
    @}
-   @defgroup viewxx View
-   @ingroup pugl_cxx
-   @copydoc view
+   @name View
    @{
 */
 
@@ -715,12 +707,9 @@ private:
 
 /**
    @}
+   @}
 */
 
 } // namespace pugl
 
-/**
-   @}
-*/
-
 #endif // PUGL_PUGL_HPP
diff --git a/include/pugl/pugl_cairo.h b/include/pugl/pugl_cairo.h
index 0e0698b..6e5a035 100644
--- a/include/pugl/pugl_cairo.h
+++ b/include/pugl/pugl_cairo.h
@@ -36,7 +36,7 @@ PUGL_BEGIN_DECLS
 /**
    Cairo graphics backend accessor.
 
-   Pass the return value to puglSetBackend() to draw to a view with Cairo.
+   Pass the returned value to puglSetBackend() to draw to a view with Cairo.
 */
 PUGL_API PUGL_CONST_FUNC const PuglBackend*
 puglCairoBackend(void);
diff --git a/include/pugl/pugl_gl.h b/include/pugl/pugl_gl.h
index 471c5ac..b0100ce 100644
--- a/include/pugl/pugl_gl.h
+++ b/include/pugl/pugl_gl.h
@@ -47,7 +47,7 @@ puglGetProcAddress(const char* name);
 /**
    OpenGL graphics backend.
 
-   Pass the return value to puglSetBackend() to draw to a view with OpenGL.
+   Pass the returned value to puglSetBackend() to draw to a view with OpenGL.
 */
 PUGL_API PUGL_CONST_FUNC const PuglBackend*
 puglGlBackend(void);
diff --git a/include/pugl/pugl_stub.h b/include/pugl/pugl_stub.h
index f50418e..569415c 100644
--- a/include/pugl/pugl_stub.h
+++ b/include/pugl/pugl_stub.h
@@ -28,21 +28,13 @@ PUGL_BEGIN_DECLS
 
 /**
    @defgroup stub Stub
-
-   Stub graphics backend.
-
-   The stub backend functions do nothing and always
-   return success.  These do not make for a usable backend on their own since
-   the platform implementation would fail to create a window, but are useful
-   for other backends to reuse since not all need non-trivial implementations
-   of every backend function.
-
+   Native graphics support.
    @ingroup pugl_c
    @{
 */
 
 /**
-   Stub graphics backend.
+   Stub graphics backend accessor.
 
    This backend just creates a simple native window without setting up any
    portable graphics API.