Improve documentation and use LV2 documentation style

1 files changed, 27 insertions, 22 deletions

diff --git a/pugl/pugl.h b/pugl/pugl.h
index 067d780..5e816f0 100644
--- a/pugl/pugl.h
+++ b/pugl/pugl.h
@@ -15,7 +15,7 @@
 */
 
 /**
-   @file pugl.h Public Pugl API.
+   @file pugl.h Public C API.
 */
 
 #ifndef PUGL_H_INCLUDED
@@ -48,30 +48,11 @@ extern "C" {
 
 /**
    @defgroup pugl Pugl
-   A minimal portable API for OpenGL.
+   Pugl C API.
    @{
 */
 
 /**
-   A Pugl view.
-*/
-typedef struct PuglViewImpl PuglView;
-
-/**
-   Graphics backend interface.
-*/
-typedef struct PuglBackendImpl PuglBackend;
-
-/**
-   A native window handle.
-
-   On X11, this is a Window.
-   On OSX, this is an NSView*.
-   On Windows, this is a HWND.
-*/
-typedef intptr_t PuglNativeWindow;
-
-/**
    Handle for opaque user data.
 */
 typedef void* PuglHandle;
@@ -428,6 +409,7 @@ typedef union {
 } PuglEvent;
 
 /**
+   @anchor world
    @name World
    The top level context of a Pugl application.
    @{
@@ -507,6 +489,7 @@ puglDispatchEvents(PuglWorld* world);
 
 /**
    @}
+   @anchor view
    @name View
    A view is a drawing region that receives events, which may correspond to a
    top-level window or be embedded in some other window.
@@ -514,6 +497,11 @@ puglDispatchEvents(PuglWorld* world);
 */
 
 /**
+   A Pugl view.
+*/
+typedef struct PuglViewImpl PuglView;
+
+/**
    Create a new view.
 
    A view represents a window, but a window will not be shown until configured
@@ -571,6 +559,7 @@ puglPostRedisplay(PuglView* view);
 
 /**
    @}
+   @anchor frame
    @name Frame
    Functions for working with the position and size of a view.
    @{
@@ -617,6 +606,15 @@ puglSetAspectRatio(PuglView* view, int minX, int minY, int maxX, int maxY);
 */
 
 /**
+   A native window handle.
+
+   On X11, this is a Window.
+   On OSX, this is an NSView*.
+   On Windows, this is a HWND.
+*/
+typedef intptr_t PuglNativeWindow;
+
+/**
    Set the title of the window.
 
    This only makes sense for non-embedded views that will have a corresponding
@@ -678,6 +676,11 @@ puglGetNativeWindow(PuglView* view);
 */
 
 /**
+   Graphics backend interface.
+*/
+typedef struct PuglBackendImpl PuglBackend;
+
+/**
    OpenGL extension function.
 */
 typedef void (*PuglGlFunc)(void);
@@ -738,7 +741,9 @@ puglLeaveContext(PuglView* view, bool drawing);
 
 /**
    @}
-   @name Event Handling
+   @anchor interaction
+   @name Interaction
+   Interacting with the system and user with events.
    @{
 */