From c3ac8395e0ae81b7587ae75d34d6f750b654582c Mon Sep 17 00:00:00 2001 From: Adrian Perez de Castro Date: Mon, 17 Jun 2019 15:23:56 +0300 Subject: [PATCH] doc: Reorganize HotDoc sources, start documenting Reorganize how documentation is structured, without using HotDoc's smart-index, and instead manually grouping the symbols in the sections where they make more sense. This allows, for example, to group the version symbols from both "version.h" and "version-deprecated.h" without them being forced to be on separate pages by the smart index. One more nicety is that this allows writing more prosaic descriptions of the different modules. Additionally, make HotDoc pick the generated headers, and do some small tweaks to its invocation. --- CMakeLists.txt | 12 ++++++---- docs/apiref.md | 1 + docs/index.md | 7 ++++++ docs/loader.md | 9 ++++++++ docs/pasteboard.md | 9 ++++++++ docs/sitemap.txt | 6 ++++- docs/version.md | 13 +++++++++++ include/wpe/loader.h | 28 ++++++++++++++++++++++ include/wpe/pasteboard.h | 32 +++++++++++++++++++++++--- include/wpe/version-deprecated.h.cmake | 24 +++++++++++++++++++ include/wpe/version.h.cmake | 15 ++++++++++++ 11 files changed, 148 insertions(+), 8 deletions(-) create mode 100644 docs/apiref.md create mode 100644 docs/index.md create mode 100644 docs/loader.md create mode 100644 docs/pasteboard.md create mode 100644 docs/version.md diff --git a/CMakeLists.txt b/CMakeLists.txt index 8c72feb6..5fb9f88c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -118,18 +118,22 @@ 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-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 + --c-index "${CMAKE_SOURCE_DIR}/docs/apiref.md" ) ELSE() MESSAGE(FATAL_ERROR "Hotdoc C extension not found... can't build the documentation.") diff --git a/docs/apiref.md b/docs/apiref.md new file mode 100644 index 00000000..b0d5c88f --- /dev/null +++ b/docs/apiref.md @@ -0,0 +1 @@ +# API Reference diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..54ff414f --- /dev/null +++ b/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. diff --git a/docs/loader.md b/docs/loader.md new file mode 100644 index 00000000..c6444ee6 --- /dev/null +++ b/docs/loader.md @@ -0,0 +1,9 @@ +--- +short-description: Loader and Initialization +symbols: + - wpe_loader_interface + - wpe_loader_init + - wpe_loader_get_loaded_implementation_library_name +... + +# Loader diff --git a/docs/pasteboard.md b/docs/pasteboard.md new file mode 100644 index 00000000..489c01ff --- /dev/null +++ b/docs/pasteboard.md @@ -0,0 +1,9 @@ +--- +short-description: Pasteboard (a.k.a. clipboard) management +symbols: + - wpe_pasteboard_string_initialize + - wpe_pasteboard_string_free + - wpe_pasteboard_get_singleton +... + +# Pasteboard diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 03c4a19b..777efc9b 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -1 +1,5 @@ -c-index \ No newline at end of file +index.md + c-index + version.md + loader.md + pasteboard.md diff --git a/docs/version.md b/docs/version.md new file mode 100644 index 00000000..9e4931fc --- /dev/null +++ b/docs/version.md @@ -0,0 +1,13 @@ +--- +short-description: Library Version +symbols: + - wpe_get_major_version + - wpe_get_minor_version + - wpe_get_micro_version + - wpe_backend_get_major_version + - wpe_backend_get_minor_version + - wpe_backend_get_micro_version +... + +# Version + diff --git a/include/wpe/loader.h b/include/wpe/loader.h index 2b60e4f3..f3bf41a6 100644 --- a/include/wpe/loader.h +++ b/include/wpe/loader.h @@ -41,18 +41,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); diff --git a/include/wpe/pasteboard.h b/include/wpe/pasteboard.h index 0e8b4615..77971fa5 100644 --- a/include/wpe/pasteboard.h +++ b/include/wpe/pasteboard.h @@ -61,13 +61,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 +101,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 diff --git a/include/wpe/version-deprecated.h.cmake b/include/wpe/version-deprecated.h.cmake index 8be48277..dc94bd52 100644 --- a/include/wpe/version-deprecated.h.cmake +++ b/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 diff --git a/include/wpe/version.h.cmake b/include/wpe/version.h.cmake index f6241d00..ffadc227 100644 --- a/include/wpe/version.h.cmake +++ b/include/wpe/version.h.cmake @@ -49,10 +49,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