From eeef6be8e2ac2e83a175adca5100c2e58cc5aa24 Mon Sep 17 00:00:00 2001 From: Marius Vlad Date: Tue, 22 Nov 2022 15:27:47 +0200 Subject: [PATCH] doc/sphinx: Include weston-config and shell-utils in docs libweston contains weston_config and weston_shell_utils utilities functions so include these in the sphinx documentation as well. Signed-off-by: Marius Vlad --- doc/sphinx/doxygen.ini.in | 1 + doc/sphinx/toc/libweston.rst | 9 +++-- doc/sphinx/toc/libweston/meson.build | 2 ++ doc/sphinx/toc/libweston/shell-utils.rst | 7 ++++ doc/sphinx/toc/libweston/weston-config.rst | 7 ++++ libweston/shell-utils/shell-utils.c | 32 ++++++++++++++++- shared/config-parser.c | 42 ++++++++++++++++++++++ 7 files changed, 96 insertions(+), 4 deletions(-) create mode 100644 doc/sphinx/toc/libweston/shell-utils.rst create mode 100644 doc/sphinx/toc/libweston/weston-config.rst diff --git a/doc/sphinx/doxygen.ini.in b/doc/sphinx/doxygen.ini.in index 29f57882..79bae0d9 100644 --- a/doc/sphinx/doxygen.ini.in +++ b/doc/sphinx/doxygen.ini.in @@ -789,6 +789,7 @@ WARN_LOGFILE = INPUT = @SRC_ROOT@/libweston \ @SRC_ROOT@/include/libweston \ + @SRC_ROOT@/shared/config-parser.c \ @SRC_ROOT@/tests # This tag can be used to specify the character encoding of the source files diff --git a/doc/sphinx/toc/libweston.rst b/doc/sphinx/toc/libweston.rst index c8a2e62d..cd56e0d1 100644 --- a/doc/sphinx/toc/libweston.rst +++ b/doc/sphinx/toc/libweston.rst @@ -6,6 +6,8 @@ Libweston :caption: Contents: libweston/compositor.rst + libweston/weston-config.rst + libweston/shell-utils.rst libweston/output-management.rst libweston/log.rst @@ -20,11 +22,12 @@ evolving through many Weston releases before it achieves a stable API and feature completeness. `Libweston`'s primary purpose is exporting an API for creating Wayland -compositors. Libweston's secondary purpose is to export the weston_config API +compositors. Libweston's secondary purpose is to export the :ref:`weston-config` API so that third party plugins and helper programs can read :file:`weston.ini` if they want to. However, these two scopes are orthogonal and independent. At no -point will the compositor functionality use or depend on the weston_config -functionality. +point will the compositor functionality use or depend on the :ref:`weston-config` +functionality. Additional helper functions are grouped together under +:ref:`shell-utils`, to ease out shell development. Further work ------------ diff --git a/doc/sphinx/toc/libweston/meson.build b/doc/sphinx/toc/libweston/meson.build index 9fdd59f4..f72ca5f2 100644 --- a/doc/sphinx/toc/libweston/meson.build +++ b/doc/sphinx/toc/libweston/meson.build @@ -5,6 +5,8 @@ files = [ 'log.rst', 'output.rst', 'output-management.rst', + 'weston-config.rst', + 'shell-utils.rst', ] foreach file : files diff --git a/doc/sphinx/toc/libweston/shell-utils.rst b/doc/sphinx/toc/libweston/shell-utils.rst new file mode 100644 index 00000000..bf390663 --- /dev/null +++ b/doc/sphinx/toc/libweston/shell-utils.rst @@ -0,0 +1,7 @@ +.. _shell-utils: + +Shell utils +=========== + +.. doxygengroup:: shell-utils + :content-only: diff --git a/doc/sphinx/toc/libweston/weston-config.rst b/doc/sphinx/toc/libweston/weston-config.rst new file mode 100644 index 00000000..e3ff9e87 --- /dev/null +++ b/doc/sphinx/toc/libweston/weston-config.rst @@ -0,0 +1,7 @@ +.. _weston-config: + +Weston config +============= + +.. doxygengroup:: weston-config + :content-only: diff --git a/libweston/shell-utils/shell-utils.c b/libweston/shell-utils/shell-utils.c index 287d60fd..4aab6876 100644 --- a/libweston/shell-utils/shell-utils.c +++ b/libweston/shell-utils/shell-utils.c @@ -28,6 +28,17 @@ #include #include +/** + * \defgroup shell-utils Shell utils + * + * These are some commonly used functions in our shells, useful for other shells + * as well. + */ + + +/** + * \ingroup shell-utils + */ WL_EXPORT struct weston_output * weston_shell_utils_get_default_output(struct weston_compositor *compositor) { @@ -38,6 +49,9 @@ weston_shell_utils_get_default_output(struct weston_compositor *compositor) struct weston_output, link); } +/** + * \ingroup shell-utils + */ WL_EXPORT struct weston_output * weston_shell_utils_get_focused_output(struct weston_compositor *compositor) { @@ -69,7 +83,11 @@ weston_shell_utils_get_focused_output(struct weston_compositor *compositor) return output; } -/* TODO: Fix this function to take into account nested subsurfaces. */ +/** + * \ingroup shell-utils + * + * TODO: Fix this function to take into account nested subsurfaces. + */ WL_EXPORT void weston_shell_utils_subsurfaces_boundingbox(struct weston_surface *surface, int32_t *x, int32_t *y, @@ -104,6 +122,9 @@ weston_shell_utils_subsurfaces_boundingbox(struct weston_surface *surface, pixman_region32_fini(®ion); } +/** + * \ingroup shell-utils + */ WL_EXPORT void weston_shell_utils_center_on_output(struct weston_view *view, struct weston_output *output) @@ -125,6 +146,9 @@ weston_shell_utils_center_on_output(struct weston_view *view, weston_view_set_position(view, x, y); } +/** + * \ingroup shell-utils + */ WL_EXPORT int weston_shell_utils_surface_get_label(struct weston_surface *surface, char *buf, size_t len) @@ -142,6 +166,9 @@ weston_shell_utils_surface_get_label(struct weston_surface *surface, c ? " of " : "", c ?: ""); } +/** + * \ingroup shell-utils + */ WL_EXPORT struct weston_curtain * weston_shell_utils_curtain_create(struct weston_compositor *compositor, struct weston_curtain_params *params) @@ -206,6 +233,9 @@ err: return NULL; } +/** + * \ingroup shell-utils + */ WL_EXPORT void weston_shell_utils_curtain_destroy(struct weston_curtain *curtain) { diff --git a/shared/config-parser.c b/shared/config-parser.c index cf4adddf..749158df 100644 --- a/shared/config-parser.c +++ b/shared/config-parser.c @@ -45,6 +45,12 @@ #include "helpers.h" #include "string-helpers.h" +/** + * \defgroup weston-config Weston configuration + * + * Helper functions to read out ini configuration file. + */ + struct weston_config_entry { char *key; char *value; @@ -130,6 +136,9 @@ config_section_get_entry(struct weston_config_section *section, return NULL; } +/** + * \ingroup weston-config + */ WL_EXPORT struct weston_config_section * weston_config_get_section(struct weston_config *config, const char *section, const char *key, const char *value) @@ -152,6 +161,9 @@ weston_config_get_section(struct weston_config *config, const char *section, return NULL; } +/** + * \ingroup weston-config + */ WL_EXPORT int weston_config_section_get_int(struct weston_config_section *section, const char *key, @@ -174,6 +186,9 @@ weston_config_section_get_int(struct weston_config_section *section, return 0; } +/** + * \ingroup weston-config + */ WL_EXPORT int weston_config_section_get_uint(struct weston_config_section *section, const char *key, @@ -210,6 +225,9 @@ weston_config_section_get_uint(struct weston_config_section *section, return 0; } +/** + * \ingroup weston-config + */ WL_EXPORT int weston_config_section_get_color(struct weston_config_section *section, const char *key, @@ -247,6 +265,9 @@ weston_config_section_get_color(struct weston_config_section *section, return 0; } +/** + * \ingroup weston-config + */ WL_EXPORT int weston_config_section_get_double(struct weston_config_section *section, const char *key, @@ -272,6 +293,9 @@ weston_config_section_get_double(struct weston_config_section *section, return 0; } +/** + * \ingroup weston-config + */ WL_EXPORT int weston_config_section_get_string(struct weston_config_section *section, const char *key, @@ -294,6 +318,9 @@ weston_config_section_get_string(struct weston_config_section *section, return 0; } +/** + * \ingroup weston-config + */ WL_EXPORT int weston_config_section_get_bool(struct weston_config_section *section, const char *key, @@ -321,6 +348,9 @@ weston_config_section_get_bool(struct weston_config_section *section, return 0; } +/** + * \ingroup weston-config + */ WL_EXPORT const char * weston_config_get_name_from_env(void) { @@ -447,6 +477,9 @@ weston_config_parse_fp(FILE *file) return config; } +/** + * \ingroup weston-config + */ WL_EXPORT struct weston_config * weston_config_parse(const char *name) { @@ -498,6 +531,9 @@ weston_config_get_full_path(struct weston_config *config) return config == NULL ? NULL : config->path; } +/** + * \ingroup weston-config + */ WL_EXPORT int weston_config_next_section(struct weston_config *config, struct weston_config_section **section, @@ -521,6 +557,9 @@ weston_config_next_section(struct weston_config *config, return 1; } +/** + * \ingroup weston-config + */ WL_EXPORT void weston_config_destroy(struct weston_config *config) { @@ -543,6 +582,9 @@ weston_config_destroy(struct weston_config *config) free(config); } +/** + * \ingroup weston-config + */ WL_EXPORT uint32_t weston_config_get_binding_modifier(struct weston_config *config, uint32_t default_mod)