better public interface and doxygen

3 files changed, 68 insertions, 7 deletions

diff --git a/include/yasl/native/cocoa.h b/include/yasl/native/cocoa.h
index 9066a19..9b221cf 100644
--- a/include/yasl/native/cocoa.h
+++ b/include/yasl/native/cocoa.h
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Typed borrowed Cocoa handles; available on macOS. Use on the main thread.
+ */
 #ifndef YASL_NATIVE_COCOA_H
 #define YASL_NATIVE_COCOA_H
 
@@ -8,9 +12,9 @@
 @class NSWindow;
 @class NSView;
 #else
-typedef struct objc_object NSApplication;
-typedef struct objc_object NSWindow;
-typedef struct objc_object NSView;
+typedef struct objc_object NSApplication; /**< Opaque Cocoa application in plain C/C++. */
+typedef struct objc_object NSWindow; /**< Opaque Cocoa window in plain C/C++. */
+typedef struct objc_object NSView; /**< Opaque Cocoa view in plain C/C++. */
 #endif
 
 #ifdef __cplusplus
@@ -18,9 +22,30 @@ extern "C" {
 #endif
 
 /* Return borrowed Cocoa handles (expire on display/surface destruction).
- * Return NULL / nil if display/surface is not a Cocoa object or destroyed. */
+ * Return NULL / nil if display/surface is not a Cocoa object or NULL. */
+/**
+ * Get the borrowed NSApplication for an object of the matching backend.
+ * @param d Live display, or NULL.
+ * @return The handle, or zero/NULL for NULL or a different backend.
+ * Expires on display destruction. Available only when this backend is built.
+ * Never pass a pointer to a destroyed object.
+ */
 YASL_API NSApplication *yasl_cocoa_display_get_application(struct yasl_display *d);
+/**
+ * Get the borrowed NSWindow for an object of the matching backend.
+ * @param s Live surface, or NULL.
+ * @return The handle, or zero/NULL for NULL or a different backend.
+ * Expires on surface destruction. Available only when this backend is built.
+ * Never pass a pointer to a destroyed object.
+ */
 YASL_API NSWindow *yasl_cocoa_surface_get_window(struct yasl_surface *s);
+/**
+ * Get the borrowed NSView for an object of the matching backend.
+ * @param s Live surface, or NULL.
+ * @return The handle, or zero/NULL for NULL or a different backend.
+ * Expires on surface destruction. Available only when this backend is built.
+ * Never pass a pointer to a destroyed object.
+ */
 YASL_API NSView *yasl_cocoa_surface_get_view(struct yasl_surface *s);
 
 #ifdef __cplusplus
diff --git a/include/yasl/native/wayland.h b/include/yasl/native/wayland.h
index 4a759d4..b11e3b8 100644
--- a/include/yasl/native/wayland.h
+++ b/include/yasl/native/wayland.h
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Typed borrowed Wayland handles; available when built with Wayland support.
+ */
 #ifndef YASL_NATIVE_WAYLAND_H
 #define YASL_NATIVE_WAYLAND_H
 
@@ -11,8 +15,22 @@ struct wl_display;
 struct wl_surface;
 
 /* Return borrowed Wayland handles (expire on display/surface destruction).
- * Return NULL if display/surface is not a Wayland object or destroyed. */
+ * Return NULL if display/surface is not a Wayland object or NULL. */
+/**
+ * Get the borrowed Wayland connection for an object of the matching backend.
+ * @param d Live display, or NULL.
+ * @return The handle, or zero/NULL for NULL or a different backend.
+ * Expires on display destruction. Available only when this backend is built.
+ * Never pass a pointer to a destroyed object.
+ */
 YASL_API struct wl_display *yasl_wayland_display_get_wl_display(struct yasl_display *d);
+/**
+ * Get the borrowed Wayland surface for an object of the matching backend.
+ * @param s Live surface, or NULL.
+ * @return The handle, or zero/NULL for NULL or a different backend.
+ * Expires on surface destruction. Available only when this backend is built.
+ * Never pass a pointer to a destroyed object.
+ */
 YASL_API struct wl_surface *yasl_wayland_surface_get_wl_surface(struct yasl_surface *s);
 
 #ifdef __cplusplus
diff --git a/include/yasl/native/x11.h b/include/yasl/native/x11.h
index c0105cb..b719b4b 100644
--- a/include/yasl/native/x11.h
+++ b/include/yasl/native/x11.h
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Typed borrowed X11 handles; available when built with X11 support.
+ */
 #ifndef YASL_NATIVE_X11_H
 #define YASL_NATIVE_X11_H
 
@@ -8,11 +12,25 @@
 extern "C" {
 #endif
 
-typedef struct _XDisplay Display;
+typedef struct _XDisplay Display; /**< Opaque Xlib connection, compatible with Xlib.h. */
 
 /* Return borrowed X11 handles (expire on display/surface destruction).
- * Return NULL / 0 if display/surface is not an X11 object or destroyed. */
+ * Return NULL / 0 if display/surface is not an X11 object or NULL. */
+/**
+ * Get the borrowed X11 Display for an object of the matching backend.
+ * @param d Live display, or NULL.
+ * @return The handle, or zero/NULL for NULL or a different backend.
+ * Expires on display destruction. Available only when this backend is built.
+ * Never pass a pointer to a destroyed object.
+ */
 YASL_API Display *yasl_x11_display_get_display(struct yasl_display *d);
+/**
+ * Get the borrowed X11 Window ID for an object of the matching backend.
+ * @param s Live surface, or NULL.
+ * @return The handle, or zero/NULL for NULL or a different backend.
+ * Expires on surface destruction. Available only when this backend is built.
+ * Never pass a pointer to a destroyed object.
+ */
 YASL_API uintptr_t yasl_x11_surface_get_window(struct yasl_surface *s);
 
 #ifdef __cplusplus