Some improvements to the documentation

CMakeLists.txt

@@ -118,17 +118,21 @@ IF(BUILD_DOCS)
   execute_process(
     COMMAND ${HOTDOC} --has-extension c-extension
     RESULT_VARIABLE HAS_HOTDOC_C_EXTENSION
+    ERROR_QUIET
   )
   IF("${HAS_HOTDOC_C_EXTENSION}" EQUAL 0)
     add_custom_target(Documentation ALL
       ${HOTDOC} run
-      --project-name=WPE
+      --project-name=libwpe
       --project-version=1.0
+      --include-paths="${CMAKE_SOURCE_DIR}/docs"
       --sitemap=${CMAKE_SOURCE_DIR}/docs/sitemap.txt
       --output=${CMAKE_CURRENT_BINARY_DIR}/Documentation/
-      --c-sources="${CMAKE_SOURCE_DIR}/include/wpe/*.[ch]"
-      --extra-c-flags=-DWPE_COMPILATION=true
-      --c-include-directories ${CMAKE_SOURCE_DIR}/include ${DERIVED_SOURCES_DIR}/..
+      --c-sources "${CMAKE_SOURCE_DIR}/include/wpe/*.h"
+                  "${DERIVED_SOURCES_DIR}/version.h"
+                  "${DERIVED_SOURCES_DIR}/version-deprecated.h"
+      --extra-c-flags=-DWPE_COMPILATION=1
+      --c-include-directories ${CMAKE_SOURCE_DIR}/include ${DERIVED_SOURCES_DIR}
       --c-smart-index
     )
   ELSE()

docs/index.md

@@ -0,0 +1,7 @@
+# libwpe 1.0
+
+`libwpe` defines interfaces which can be used by
+[WebKit](https://webkit.org), and a mechanism for loading a *WPE backend*
+which implements them. Using the public `libwpe` API decouples WebKit from
+the platform-specific behaviour, which is implemented by each individual
+backend.

docs/sitemap.txt

@@ -1 +1,2 @@
-c-index
+index.md
+	c-index

include/wpe/input.h

@@ -31,6 +31,12 @@
 #ifndef wpe_input_h
 #define wpe_input_h
 
+/**
+ * SECTION:input
+ * @short_description: Input Handling
+ * @title: Input
+ */
+
 #if defined(WPE_COMPILATION)
 #include <wpe/export.h>
 #endif

include/wpe/loader.h

@@ -31,6 +31,12 @@
 #ifndef wpe_loader_h
 #define wpe_loader_h
 
+/**
+ * SECTION:loader
+ * @short_description: Loader and Initialization
+ * @title: Loader
+ */
+
 #if defined(WPE_COMPILATION)
 #include <wpe/export.h>
 #endif
@@ -41,18 +47,46 @@
 extern "C" {
 #endif
 
+/**
+ * wpe_loader_interface:
+ * @load_object: Callback invoked by `libwpe` to instantiate objects.
+ *
+ * An implementation of a WPE backend *must* define a `_wpe_loader_interface`
+ * symbol of this type.
+ */
 struct wpe_loader_interface {
     void* (*load_object)(const char*);
+
+    /*< private >*/
     void (*_wpe_reserved0)(void);
     void (*_wpe_reserved1)(void);
     void (*_wpe_reserved2)(void);
     void (*_wpe_reserved3)(void);
 };
 
+/**
+ * wpe_loader_init:
+ * @impl_library_name: (transfer none): Name of the shared library object
+ *     to load as WPE backend implementation.
+ *
+ * Initializes the `libwpe` object loader
+ *
+ * Returns: Whether initialization succeeded.
+ */
 WPE_EXPORT
 bool
 wpe_loader_init(const char* impl_library_name);
 
+/**
+ * wpe_loader_get_loaded_implementation_library_name:
+ *
+ * Obtain the name of the shared library object loaded as WPE backend
+ * implementation. Note that in general this will return the value passed
+ * to wpe_loader_init(), but that is not guaranteed.
+ *
+ * Returns: (transfer none): Name of the shared library object for the
+ *     backend implementation.
+ */
 WPE_EXPORT
 const char*
 wpe_loader_get_loaded_implementation_library_name(void);

include/wpe/pasteboard.h

@@ -31,6 +31,12 @@
 #ifndef wpe_pasteboard_h
 #define wpe_pasteboard_h
 
+/**
+ * SECTION:pasteboard
+ * @short_description: Pasteboard (a.k.a. clipboard) Management
+ * @title: Pasteboard
+ */
+
 #if defined(WPE_COMPILATION)
 #include <wpe/export.h>
 #endif
@@ -61,13 +67,31 @@ struct wpe_pasteboard_string_map {
     uint64_t length;
 };
 
+/**
+ * wpe_pasteboard_string_initialize:
+ * @pbstring: (transfer none): A pasteboard string.
+ * @contents: (transfer none): Contents to copy into the pasteboard string.
+ * @length: Length of the contents, in bytes.
+ *
+ * Initializes a pasteboard string.
+ *
+ * When the string is not needed anymore, use wpe_pasteboard_string_free()
+ * to free resources.
+ */
 WPE_EXPORT
 void
-wpe_pasteboard_string_initialize(struct wpe_pasteboard_string*, const char*, uint64_t);
+wpe_pasteboard_string_initialize(struct wpe_pasteboard_string* pbstring, const char* contents, uint64_t length);
 
+/**
+ * wpe_pasteboard_string_free:
+ * @pbstring: (transfer none): A pasteboard string.
+ *
+ * Frees any resources associated with @pbstring which may have been
+ * previously allocated by wpe_pasteboard_string_initialize().
+ */
 WPE_EXPORT
 void
-wpe_pasteboard_string_free(struct wpe_pasteboard_string*);
+wpe_pasteboard_string_free(struct wpe_pasteboard_string* pbstring);
 
 WPE_EXPORT
 void
@@ -83,15 +107,23 @@ struct wpe_pasteboard_interface {
     void (*get_string)(void*, const char*, struct wpe_pasteboard_string*);
     void (*write)(void*, struct wpe_pasteboard_string_map*);
 
+    /*< private >*/
     void (*_wpe_reserved0)(void);
     void (*_wpe_reserved1)(void);
     void (*_wpe_reserved2)(void);
     void (*_wpe_reserved3)(void);
 };
 
+/**
+ * wpe_pasteboard_get_singleton:
+ *
+ * Obtains the pasteboard object, creating it if neccessary.
+ *
+ * Returns: The pasteboard object.
+ */
 WPE_EXPORT
 struct wpe_pasteboard*
-wpe_pasteboard_get_singleton();
+wpe_pasteboard_get_singleton(void);
 
 WPE_EXPORT
 void

include/wpe/renderer-backend-egl.h

@@ -31,6 +31,12 @@
 #ifndef wpe_renderer_backend_egl_h
 #define wpe_renderer_backend_egl_h
 
+/**
+ * SECTION:egl-renderer
+ * @short_description: EGL Renderer Backend
+ * @title: EGL Renderer
+ */
+
 #if defined(WPE_COMPILATION)
 #include <wpe/export.h>
 #endif
@@ -55,6 +61,7 @@ struct wpe_renderer_backend_egl_interface {
     EGLNativeDisplayType (*get_native_display)(void*);
     uint32_t (*get_platform)(void*);
 
+    /*< private >*/
     void (*_wpe_reserved1)(void);
     void (*_wpe_reserved2)(void);
     void (*_wpe_reserved3)(void);
@@ -70,6 +77,7 @@ struct wpe_renderer_backend_egl_target_interface {
     void (*frame_will_render)(void*);
     void (*frame_rendered)(void*);
 
+    /*< private >*/
     void (*_wpe_reserved0)(void);
     void (*_wpe_reserved1)(void);
     void (*_wpe_reserved2)(void);
@@ -83,6 +91,7 @@ struct wpe_renderer_backend_egl_offscreen_target_interface {
     void (*initialize)(void*, void*);
     EGLNativeWindowType (*get_native_window)(void*);
 
+    /*< private >*/
     void (*_wpe_reserved0)(void);
     void (*_wpe_reserved1)(void);
     void (*_wpe_reserved2)(void);
@@ -155,6 +164,8 @@ wpe_renderer_backend_egl_offscreen_target_get_native_window(struct wpe_renderer_
 
 struct wpe_renderer_backend_egl_target_client {
     void (*frame_complete)(void*);
+
+    /*< private >*/
     void (*_wpe_reserved0)(void);
     void (*_wpe_reserved1)(void);
     void (*_wpe_reserved2)(void);

include/wpe/renderer-host.h

@@ -31,6 +31,12 @@
 #ifndef wpe_renderer_host_h
 #define wpe_renderer_host_h
 
+/**
+ * SECTION:renderer
+ * @short_description: Renderer Host
+ * @title: Renderer
+ */
+
 #if defined(WPE_COMPILATION)
 #include <wpe/export.h>
 #endif
@@ -45,6 +51,7 @@ struct wpe_renderer_host_interface {
 
     int (*create_client)(void*);
 
+    /*< private >*/
     void (*_wpe_reserved0)(void);
     void (*_wpe_reserved1)(void);
     void (*_wpe_reserved2)(void);

include/wpe/version-deprecated.h.cmake

@@ -49,10 +49,34 @@ extern "C" {
     (WPE_BACKEND_MAJOR_VERSION == (major) && WPE_BACKEND_MINOR_VERSION == (minor) && \
      WPE_BACKEND_MICRO_VERSION >= (micro)))
 
+/**
+ * wpe_backend_get_major_version:
+ *
+ * Returns: Major version of the `libwpe` library.
+ *
+ * Deprecated: Since `libwpe` version 1.0.0, use wpe_get_major_version()
+ *     instead.
+ */
 WPE_EXPORT unsigned wpe_backend_get_major_version(void);
 
+/**
+ * wpe_backend_get_minor_version:
+ *
+ * Returns: Minor version of the `libwpe` library.
+ *
+ * Deprecated: Since `libwpe` version 1.0.0, use wpe_get_minor_version()
+ *     instead.
+ */
 WPE_EXPORT unsigned wpe_backend_get_minor_version(void);
 
+/**
+ * wpe_backend_get_micro_version:
+ *
+ * Returns: Micro version of the `libwpe` library.
+ *
+ * Deprecated: Since `libwpe` version 1.0.0, use wpe_get_micro_version()
+ *     instead.
+ */
 WPE_EXPORT unsigned wpe_backend_get_micro_version(void);
 
 #ifdef __cplusplus

include/wpe/version.h.cmake

@@ -31,6 +31,16 @@
 #ifndef wpe_version_h
 #define wpe_version_h
 
+/**
+ * SECTION:version
+ * @short_description: Library Version
+ * @title: Version
+ * @symbols:
+ *   - wpe_backend_get_major_version
+ *   - wpe_backend_get_minor_version
+ *   - wpe_backend_get_micro_version
+ */
+
 #if defined(WPE_COMPILATION)
 #include <wpe/export.h>
 #endif
@@ -49,10 +59,25 @@ extern "C" {
     (WPE_MAJOR_VERSION == (major) && WPE_MINOR_VERSION == (minor) && \
      WPE_MICRO_VERSION >= (micro)))
 
+/**
+ * wpe_get_major_version:
+ *
+ * Returns: Major version of the `libwpe` library.
+ */
 WPE_EXPORT unsigned wpe_get_major_version(void);
 
+/**
+ * wpe_get_minor_version:
+ *
+ * Returns: Minor version of the `libwpe` library.
+ */
 WPE_EXPORT unsigned wpe_get_minor_version(void);
 
+/**
+ * wpe_get_micro_version:
+ *
+ * Returns: Micro version of the `libwpe` library.
+ */
 WPE_EXPORT unsigned wpe_get_micro_version(void);
 
 #ifdef __cplusplus

include/wpe/view-backend.h

@@ -31,6 +31,12 @@
 #ifndef wpe_view_backend_h
 #define wpe_view_backend_h
 
+/**
+ * SECTION:view-backend
+ * @short_description: View Backend
+ * @title: View Backend
+ */
+
 #if defined(WPE_COMPILATION)
 #include <wpe/export.h>
 #endif
@@ -58,6 +64,7 @@ struct wpe_view_backend_interface {
     void (*initialize)(void*);
     int (*get_renderer_host_fd)(void*);
 
+    /*< private >*/
     void (*_wpe_reserved0)(void);
     void (*_wpe_reserved1)(void);
     void (*_wpe_reserved2)(void);
@@ -105,6 +112,8 @@ struct wpe_view_backend_client {
     void (*activity_state_changed)(void*, uint32_t);
     void* (*get_accessible)(void*);
     void (*set_device_scale_factor)(void*, float);
+
+    /*< private >*/
     void (*_wpe_reserved0)(void);
 };
 
@@ -141,6 +150,8 @@ struct wpe_view_backend_input_client {
     void (*handle_pointer_event)(void*, struct wpe_input_pointer_event*);
     void (*handle_axis_event)(void*, struct wpe_input_axis_event*);
     void (*handle_touch_event)(void*, struct wpe_input_touch_event*);
+
+    /*< private >*/
     void (*_wpe_reserved0)(void);
     void (*_wpe_reserved1)(void);
     void (*_wpe_reserved2)(void);