aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2020-03-07 18:27:44 +0100
committerDavid Robillard <d@drobilla.net>2020-03-07 18:28:15 +0100
commit0a4e6e1568e2369d80ed7ac9af4751dc2a276364 (patch)
tree1e5074495f318fac62631f2cc5e64ecdd51c116d
parentc0c6e93c0c3702fdd7a3f9fb4927dd7f7271000d (diff)
Organize documentation into groups
-rw-r--r--pugl/pugl.h50
-rw-r--r--pugl/pugl.hpp16
-rw-r--r--pugl/pugl_cairo.h2
-rw-r--r--pugl/pugl_gl.h2
-rw-r--r--pugl/pugl_stub.h2
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
@{
*/