From 92937b14c733a344d7554d2edfd449a7b4ad63ff Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Sun, 18 Aug 2019 13:16:52 +0200
Subject: Improve documentation and use LV2 documentation style

---
 pugl/pugl.h   | 49 +++++++++++++++++++++++++++----------------------
 pugl/pugl.hpp |  4 ++--
 2 files changed, 29 insertions(+), 24 deletions(-)

(limited to 'pugl')

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,29 +48,10 @@ 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.
 */
@@ -428,6 +409,7 @@ typedef union {
 } PuglEvent;
 
 /**
+   @anchor world
    @name World
    The top level context of a Pugl application.
    @{
@@ -507,12 +489,18 @@ 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.
    @{
 */
 
+/**
+   A Pugl view.
+*/
+typedef struct PuglViewImpl PuglView;
+
 /**
    Create a new view.
 
@@ -571,6 +559,7 @@ puglPostRedisplay(PuglView* view);
 
 /**
    @}
+   @anchor frame
    @name Frame
    Functions for working with the position and size of a view.
    @{
@@ -616,6 +605,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.
 
@@ -677,6 +675,11 @@ puglGetNativeWindow(PuglView* view);
    @{
 */
 
+/**
+   Graphics backend interface.
+*/
+typedef struct PuglBackendImpl PuglBackend;
+
 /**
    OpenGL extension function.
 */
@@ -738,7 +741,9 @@ puglLeaveContext(PuglView* view, bool drawing);
 
 /**
    @}
-   @name Event Handling
+   @anchor interaction
+   @name Interaction
+   Interacting with the system and user with events.
    @{
 */
 
diff --git a/pugl/pugl.hpp b/pugl/pugl.hpp
index c2602dd..dee8c17 100644
--- a/pugl/pugl.hpp
+++ b/pugl/pugl.hpp
@@ -15,7 +15,7 @@
 */
 
 /**
-   @file pugl.hpp Public Pugl C++ API wrapper.
+   @file pugl.hpp Pugl C++ API wrapper.
 */
 
 #ifndef PUGL_HPP_INCLUDED
@@ -25,7 +25,7 @@
 
 /**
    @defgroup puglmm Puglmm
-   C++ API wrapper for Pugl.
+   Pugl C++ API wrapper.
    @{
 */
 
-- 
cgit v1.2.1