SymbX/feedbackd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'gi-docgen' into 'main'

Browse Source 
Switch library documentation to gi-docgen

Closes #56

See merge request Librem5/feedbackd!94
This commit is contained in:
Guido Gunther
2022-12-08 09:04:40 +00:00
parent 1e3175301c 6acdb67b78
commit 7ab5af7269
23 changed files with 284 additions and 334 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+4 -4
View File
@@ -67,7 +67,7 @@ See `examples/` for a simple python example using GObject introspection.
# How it works
We're using a [event naming spec](./Event-naming-spec-0.0.0.md)
We're using a [event naming spec](./doc/Event-naming-spec-0.0.0.md)
similar to http://0pointer.de/public/sound-naming-spec.html to name
events. This will allow us to act as a system sound library so
applications only need to call into this library and things like
@@ -221,8 +221,8 @@ GSETTINGS_SCHEMA_DIR=_build/data/ gsettings set org.sigxcpu.feedbackd.applicatio
# Documentation
- [Libfeedback API](https://honk.sigxcpu.org/projects/feedbackd/doc/)
- [Event naming spec draft](./Event-naming-spec-0.0.0.md)
- [Feedback-theme-spec draft](./Feedback-theme-spec-0.0.0.md)
- [Event naming spec draft](./doc/Event-naming-spec-0.0.0.md)
- [Feedback-theme-spec draft](./doc/Feedback-theme-spec-0.0.0.md)
[debian/control]: ./debian/control#L5
[1]: https://source.puri.sm/Librem5/feedbackd-device-themes)
[1]: https://source.puri.sm/Librem5/feedbackd-device-themes
data/meson.build
+1 -1
View File
@@ -59,7 +59,7 @@ if json_glib_validate.found()
build_by_default: true,
input: theme_json,
output: 'json_validate_stamp',
command: [json_glib_validate.path()] + jsons)
command: [json_glib_validate.full_path()] + jsons)
endif
endif # daemon
debian/control
Vendored
+3 -3
View File
@@ -5,9 +5,10 @@ Maintainer: Guido Günther <agx@sigxcpu.org>
Build-Depends:
dbus,
debhelper-compat (= 12),
docbook-xsl <!nodoc>,
dh-sequence-gir,
gsettings-desktop-schemas <!nocheck>,
gtk-doc-tools,
gi-docgen <!nodoc>,
json-glib-tools,
libgirepository1.0-dev,
libglib2.0-dev,
@@ -17,6 +18,7 @@ Build-Depends:
meson,
pkg-config,
valac,
xsltproc <!nodoc>,
Standards-Version: 4.4.0
Homepage: https://source.puri.sm/Librem5/feedbackd
@@ -80,8 +82,6 @@ Description: Development files for libfeedback
Package: gir1.2-lfb-0.0
Architecture: any
Section: introspection
Breaks: gir1.2-feedback-0.0 (<< 0.0.0+git20200420)
Replaces: gir1.2-feedback-0.0 (<< 0.0.0+git20200420)
Depends:
${gir:Depends},
${misc:Depends},
debian/libfeedback-dev.install
Vendored
+1 -1
View File
@@ -1,6 +1,6 @@
/usr/include
/usr/share/gir-1.0/
/usr/share/gtk-doc/
/usr/share/doc/libfeedback-0 /usr/share/doc/libfeedback-dev/
/usr/share/vala/
/usr/lib/*/libfeedback-*.so
/usr/lib/*/pkgconfig/libfeedback-*.pc
debian/libfeedback-dev.links
Vendored
+1
View File
@@ -0,0 +1 @@
usr/share/doc/libfeedback-dev/libfeedback-0 usr/share/devhelp/books/libfeedback-0
debian/rules
Vendored
+5 -1
View File
@@ -2,11 +2,15 @@
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
ifeq (,$(filter nocheck,$(DEB_BUILD_PROFILES)))
CONFIGURE_OPTS = -Dgtk_doc=true -Dman=true
endif
%:
dh $@ --builddirectory=_build
override_dh_auto_configure:
dh_auto_configure -- -Dgtk_doc=true -Dman=true
dh_auto_configure -- $(CONFIGURE_OPTS)
override_dh_installudev:
# Make sure all the symlink rules in 60 ran:
Event-naming-spec-0.0.0.md → doc/Event-naming-spec-0.0.0.md
+4 -1
View File
@@ -1,4 +1,5 @@
This is similar in spirit (and heavily based on) to the [Sound naming spec][].
Title: Event Naming Specification
Slug: Event Naming Specification
# Overview
@@ -11,6 +12,8 @@ Events, and a larger list with many more examples to help with the
creation of extended Events for third party applications, with
different event types and usage.
This is similar in spirit (and heavily based on) to the [Sound naming spec][].
# Context
The list of default contexts for the feedback theme are:
Feedback-theme-spec-0.0.0.md → doc/Feedback-theme-spec-0.0.0.md
+5 -2
View File
@@ -1,3 +1,6 @@
Title: Feedback Theme Specification
Slug: Feedback Theme Specification
# Overview
A feedback theme defines the kind of feedback that events (as
@@ -64,7 +67,7 @@ silent:
```
At the time of writing the theme format is daemon dependent. E.g. feedbackd
uses a format [similar to the above in JSON](./data/default.json).
uses a format [similar to the above in JSON](https://source.puri.sm/Librem5/feedbackd/-/blob/main/data/default.json)
# Recommendations
@@ -75,4 +78,4 @@ uses a format [similar to the above in JSON](./data/default.json).
be used.
- The full feedback theme can use any available feedback mechanisms
[Event naming spec]: ./Event-naming-spec-0.0.0.md
[Event naming spec]: https://source.puri.sm/Librem5/feedbackd/-/blob/main/doc/Event-naming-spec-0.0.0.md
doc/build-howto.md
+57
View File
@@ -0,0 +1,57 @@
Title: Compiling with libfeedback
Slug: building
# Compiling with libfeedback
If you need to build libfeedback, get the source from
[here](https://source.puri.sm/Librem5/feedbackd) and see the `README.md` file.
## Using `pkg-config`
Like other GObject based libraries, libfeedback uses `pkg-config` to provide compiler
options. The package name is `libfeedback-0.0`.
When using the Meson build system you can declare a dependency like:
```meson
dependency('libfeedback-0.0')
```
## Bundling the Library
### Using a Subproject
Libfeedback can be used as a Meson subproject. Create a
`subprojects/libfeedback.wrap` file with the following contents:
```ini
[wrap-git]
directory=libfeedback
url=https://source.puri.sm/Librem5/feedbackd.git
revision=main
depth=1
```
Add this to your `meson.build`:
```meson
libfeedback = dependency(
'libfeedback-0.0',
version: '>= 0.0.1',
fallback: ['libfeedback', 'libfeedback_dep'],
default_options: [
'daemon=false',
'man=false',
'gtk_doc=false',
'vapi=false',
'tests=false',
]
)
```
Then the `libfeedback` variable can be used as a dependency.
# Next Steps
Once libfeedback has been compiled and included into your project, it needs to be
initialized. See [Initialization](initialization.html).
doc/fbcli.xml
+1 -1
View File
@@ -52,7 +52,7 @@ print help and exit
<para>
Submit the given event to <command>feedbackd</command>. Valid events are
listes in the event naming spec at
<ulink url="https://source.puri.sm/Librem5/feedbackd/-/blob/main/Event-naming-spec-0.0.0.md"/>
<ulink url="https://source.puri.sm/Librem5/feedbackd/-/blob/main/doc/Event-naming-spec-0.0.0.md"/>
</para>
</varlistentry>
doc/initialization.md
+34
View File
@@ -0,0 +1,34 @@
Title: Initialization
Slug: initialization
# Initialization
Before using libfeedback, it must be initialized. To use the library
call [func@Lfb.init]() with the id of your application (usually
the desktop file name without the .desktop extension). For that you
include the `libfeedback.h` header. Since the API is considered
unstable at this point in time you need to acknowledge this by
definining `LIBFEEDBACK_USE_UNSTABLE_API`:
```c
#define LIBFEEDBACK_USE_UNSTABLE_API
#include <libfeedback.h>
int main(void)
{
g_autoptr (GError) *err = NULL;
if (lfb_init ("com.example.appid", &err)) {
g_error ("%s", err->message);
}
...
lfb_uninit ();
return 0;
}
```
You can also acknowledge this with the definition option of your C
compiler, like `-DFEEDBACK_USE_UNSTABLE_API`.
After initializing the library you can trigger feedback using
[class@Lfb.Event] objects. When your application finishes call
[func@Lfb.uninit]() to free any resources:
doc/libfeedback-docs.xml
-68
View File
@@ -1,68 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
]>
<book id="index">
<bookinfo>
<title>&package_name; Reference Manual</title>
<releaseinfo>
<para>This document is the API reference for &package_name; &package_version;</para>
<para>
<ulink type="http" url="&package_url;">Libfeedback</ulink> is a library to trigger
feedback (such as haptic feedback) via events sent by your application.
</para>
<para>
If you find any issues in this API reference, please report it using
<ulink type="http" url="&package_bugreport;">the bugtracker</ulink>.
</para>
</releaseinfo>
<copyright>
<year>2020</year>
<holder>Purism SPC</holder>
</copyright>
</bookinfo>
<xi:include href="overview.xml"/>
<part>
<title>API Reference</title>
<chapter id="core-api">
<title>Core API</title>
<xi:include href="xml/libfeedback.xml"/>
<xi:include href="xml/lfb-event.xml"/>
</chapter>
<chapter id="low-level-api">
<title>Low level api</title>
<xi:include href="xml/lfb-gdbus.xml"/>
<xi:include href="xml/lfb-names.xml"/>
</chapter>
<chapter id="dbus-interface">
<title>DBus Interface</title>
<xi:include href="../data/libfeedback-org.sigxcpu.Feedback.xml"/>
</chapter>
</part>
<chapter id="object-tree">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</chapter>
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="annotations-glossary">
<title>Annotations glossary</title>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</index>
</book>
doc/libfeedback.toml.in
+44
View File
@@ -0,0 +1,44 @@
[library]
version = "@VERSION@"
description = "A library to trigger feedback (such as haptic feedback) via events sent by your application."
authors = "Purism SPC"
license = "LGPL-2.1-or-later"
browse_url = "https://source.puri.sm/Librem5/feedbackd/"
repository_url = "https://source.puri.sm/Librem5/feedbackd.git"
website_url = "https://source.puri.sm/Librem5/feedbackd/"
dependencies = [
"Gio-2.0",
"GLib-2.0",
]
devhelp = true
search_index = true
[dependencies."Gio-2.0"]
name = "GIO"
description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
docs_url = "https://docs.gtk.org/gio/"
[dependencies."GLib-2.0"]
name = "GLib "
description = "The base type system library"
docs_url = "https://docs.gtk.org/glib/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[source-location]
# The base URL for the web UI
base_url = "https://source.puri.sm/Librem5/feedbackd/-/blob/main/"
# The format for links, using "filename" and "line" for the format
file_format = "{filename}#L{line}"
[extra]
content_files = [
"overview.md",
"build-howto.md",
"initialization.md",
"Event-naming-spec-0.0.0.md",
"Feedback-theme-spec-0.0.0.md",
]
doc/meson.build
+42 -32
View File
@@ -1,41 +1,51 @@
if get_option('gtk_doc')
subdir('xml')
private_headers = [
expand_content_md_files = [
'overview.md',
'build-howto.md',
'initialization.md',
'Event-naming-spec-0.0.0.md',
'Feedback-theme-spec-0.0.0.md',
]
content_files = [
'overview.xml',
]
toml_data = configuration_data()
toml_data.set('VERSION', meson.project_version())
glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
docpath = join_paths(get_option('datadir'), 'gtk-doc', 'html')
libfeedback_toml = configure_file(
input: 'libfeedback.toml.in',
output: 'libfeedback.toml',
configuration: toml_data
)
dependency('gi-docgen', version: '>= 2021.1',
fallback: ['gi-docgen', 'dummy_dep'],
native: true,
required: get_option('gtk_doc'))
gidocgen = find_program('gi-docgen')
docs_dir = datadir / 'doc'
custom_target('libfeedback-doc',
input: [ libfeedback_toml, libfeedback_gir[0] ],
output: 'libfeedback-0',
command: [
gidocgen,
'generate',
'--quiet',
'--add-include-path=@0@'.format(meson.current_build_dir() / '../src'),
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--no-namespace-dir',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
depend_files: [ expand_content_md_files ],
build_by_default: true,
install: true,
install_dir: docs_dir,
)
gnome.gtkdoc('libfeedback',
main_xml: 'libfeedback-docs.xml',
src_dir: [
join_paths(meson.source_root(), 'libfeedback'),
join_paths(meson.build_root(), 'libfeedback'),
join_paths(meson.build_root(), 'data'),
],
dependencies: libfeedback_dep,
gobject_typesfile: 'libfeedback.types',
scan_args: [
'--rebuild-types',
'--ignore-headers=' + ' '.join(private_headers),
],
fixxref_args: [
'--html-dir=@0@'.format(docpath),
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
'--extra-dir=@0@'.format(join_paths(glib_docpath, 'gi')),
],
install_dir: 'libfeedback',
content_files: content_files,
install: true)
endif
if get_option('man')
doc/overview.md
+23
View File
@@ -0,0 +1,23 @@
Title: Overview
Slug: Overview
# Libfeedback Introduction
The purpose of libfeedback is to make it simple to supply audible,
haptic and visual feedback to the user. This is done by
notifying a feedback_daemon over DBus that a certain event
happened. The daemon then selects the appropriate feedbacks (such
as a buzzing haptic motor or playing an audio file) based on the
user session's current feedback profile, feedback theme and
available hardware.
Events are identified by strings like `message-new-sms` or
`message-new-sms`. The available event names are described in the
[Event naming specification](Event-naming-spec-0.0.0.html).
Libfeedback provides synchronous and asynchronous APIs to trigger and
stop feedback for these events and is usable from other languages than
C by GObject introspection.
See [Compiling with libfeedback](build-howto.html) on how to include
libfeedback in your project.
doc/overview.xml
-111
View File
@@ -1,111 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
]>
<part>
<title>Libfeedback Overview</title>
<chapter>
<title>Introduction</title>
<para>
The purpose of libfeedback is to make it simple to supply
audible, haptic and visual feedback to the user. This is done
by notifying a &feedback_daemon; over DBus that a certain event
happened and the daemon selects the appropriate feedbacks (such as
a buzzing haptic motor or playing an audio file) based
on the user session's current feedback profile, feedback theme and available
hardware. Events are identified by strings like
<literal>message-new-sms</literal> or
<literal>message-new-sms</literal>. The available event names are
described in the &event_naming_spec;.
</para>
<para>
&package; provides synchronous and asynchronous APIs to trigger
and stop feedback for these events and is usable from other languages
than C by GObject introspection.
</para>
</chapter>
<chapter>
<title>Compiling libfeedback applications</title>
<simplesect>
<title>Using pkg-config</title>
<para> Like other GNOME libraries,
<application>&package_string;</application> uses
<application>pkg-config</application> to provide compiler options. The
package name is
"<literal>&package_ver_str;</literal>". So in
your <literal>configure.ac</literal> script, you might specify something
like: </para>
<informalexample><programlisting>
PKG_CHECK_MODULES(LIBFEEDBACK, [&package_string;-&package_api_version;])
AC_SUBST(LIBFEEDBACK_CFLAGS)
AC_SUBST(LIBFEEDBACK_LIBS)
</programlisting></informalexample>
</simplesect>
<simplesect>
<title>Using Meson/Ninja</title>
<para>
If using Meson/Ninja use a <literal>dependency('&package_string;-&package_api_version;')
</literal> dependency.
</para>
<para>
The "<literal>&package_api_version;</literal>" in the package name is the "API version"
(indicating "the version of the <application>&package_string;</application> API
that first appeared in version &package_api_version;") and is essentially just part of
the package name.
</para>
<para>
When using the Meson build system you can declare a dependency like
</para>
<informalexample><programlisting>
dependency(libfeedback-0.0')
</programlisting></informalexample>
</simplesect>
<simplesect>
<title>Acknowledge the Instability</title>
<para>
Since the library is young and is still changing a lot, in order to use it you are required to acknowledge that your are using an unstable API.
To do so, <literal>LIBFEEDBACK_USE_UNSTABLE_API</literal> must be defined for compilation to succeed.
</para>
<para>
From C code or any compatible language, you can prefix your inclusion of the &package_string; header like so:
</para>
<informalexample><programlisting>
#define LIBFEEDBACK_USE_UNSTABLE_API
#include &lt;libfeedback.h&gt;
</programlisting></informalexample>
<para>
Including individual headers rather than <literal>libfeedback.h</literal> is not
recommended.
</para>
<para>
You can also acknowledge this with the definition option of your C compiler, like <literal>-DFEEDBACK_USE_UNSTABLE_API</literal>.
This is required from Vala.
</para>
<para>
To use &package_name; from Vala, you must define the acknowledgment in C via <literal>-X -DFEEDBACK_USE_UNSTABLE_API</literal>.
If your build system uses a two pass compilation and hence your Vala compiler outputs C (Meson, Automake, or using the <literal>--ccode</literal> Vala compiler option trigger that) then you must add <literal>-DLIBFEEDBACK_USE_UNSTABLE_API</literal> to your C compiler arguments instead.
</para>
</simplesect>
</chapter>
</part>
doc/xml/gtkdocentities.ent.in
-11
View File
@@ -1,11 +0,0 @@
<!ENTITY package "@PACKAGE@">
<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
<!ENTITY package_name "@PACKAGE_NAME@">
<!ENTITY package_string "@PACKAGE_STRING@">
<!ENTITY package_tarname "@PACKAGE_TARNAME@">
<!ENTITY package_url "@PACKAGE_URL@">
<!ENTITY package_version "@PACKAGE_VERSION@">
<!ENTITY package_api_version "@PACKAGE_API_VERSION@">
<!ENTITY package_ver_str "@PACKAGE_STRING@-@PACKAGE_API_VERSION@">
<!ENTITY event_naming_spec "<ulink url='https://source.puri.sm/Librem5/feedbackd/blob/main/Event-naming-spec-0.0.0.md#standard-event-names'>Event naming specification draft</ulink>">
<!ENTITY feedback_daemon "<ulink url='https://source.puri.sm/Librem5/feedbackd/blob/main/README.md'>Feedback Daemon</ulink>">
doc/xml/meson.build
-11
View File
@@ -1,11 +0,0 @@
ent_conf = configuration_data()
ent_conf.set('PACKAGE', 'libfeedback')
ent_conf.set('PACKAGE_BUGREPORT', 'https://source.puri.sm/Librem5/feedbackd/issues')
ent_conf.set('PACKAGE_NAME', 'libfeedback')
ent_conf.set('PACKAGE_STRING', 'libfeedback')
ent_conf.set('PACKAGE_TARNAME', 'libfeedback-' + meson.project_version())
ent_conf.set('PACKAGE_URL', 'https://source.puri.sm/Librem5/feedbackd')
ent_conf.set('PACKAGE_VERSION', meson.project_version())
ent_conf.set('PACKAGE_API_VERSION', apiversion)
configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf)
libfeedback/lfb-event.c
+53 -55
View File
@@ -10,7 +10,7 @@
#include <gio/gio.h>
/**
* SECTION:lfb-event
* LfbEvent:
* @Short_description: An event triggering feedback to the user
* @Title: LfbEvent
*
@@ -23,53 +23,53 @@
* One event can trigger multiple feedbacks at once (e.g. audio and
* haptic feedback). This is determined by the feedback theme in
* use (which is not under the appliction's control) and the active
* feedback profile (see #lfb_set_feedback_profile()).
* feedback profile (see [func@Lfb.set_feedback_profile]().
*
* After initializing the library via #lfb_init() feedback can be
* After initializing the library via [func@Lfb.init]() feedback can be
* triggered like:
*
* |[
* g_autoptr (GError) err = NULL;
* LfbEvent *event = lfb_event_new ("message-new-instant");
* lfb_event_set_timeout (event, 0);
* if (!lfb_event_trigger_feedback (event, &err))
* g_warning ("Failed to trigger feedback: %s", err->message);
* ]|
* ```c
* g_autoptr (GError) err = NULL;
* LfbEvent *event = lfb_event_new ("message-new-instant");
* lfb_event_set_timeout (event, 0);
* if (!lfb_event_trigger_feedback (event, &err))
* g_warning ("Failed to trigger feedback: %s", err->message);
* ```
*
* When all feedback for this event has ended the #LfbEvent::feedback-ended
* When all feedback for this event has ended the [signal@LfbEvent::feedback-ended]
* signal is emitted. If you want to end the feedback ahead of time use
* #lfb_event_end_feedback ():
* [method@LfbEvent.end_feedback]():
*
* |[
* if (!lfb_event_end_feedback (event, &err))
* g_warning ("Failed to end feedback: %s", err->message);
* ]|
* ```c
* if (!lfb_event_end_feedback (event, &err))
* g_warning ("Failed to end feedback: %s", err->message);
* ```
*
* Since these methods involve DBus calls there are asynchronous variants
* available, e.g. #lfb_event_trigger_feedback_async():
* available, e.g. [method@LfbEvent.trigger_feedback_async]():
*
* |[
* static void
* on_feedback_triggered (LfbEvent *event,
* GAsyncResult *res,
* gpointer unused)
* {
* g_autoptr (GError) err = NULL;
* if (!lfb_event_trigger_feedback_finish (event, res, &err)) {
* g_warning ("Failed to trigger feedback for %s: %s",
* lfb_event_get_event (event), err->message);
* }
* }
* ```c
* static void
* on_feedback_triggered (LfbEvent *event,
* GAsyncResult *res,
* gpointer unused)
* {
* g_autoptr (GError) err = NULL;
* if (!lfb_event_trigger_feedback_finish (event, res, &err)) {
* g_warning ("Failed to trigger feedback for %s: %s",
* lfb_event_get_event (event), err->message);
* }
* }
*
* static void
* my_function ()
* {
* LfbEvent *event = lfb_event_new ("message-new-instant");
* lfb_event_trigger_feedback_async (event, NULL,
* (GAsyncReadyCallback)on_feedback_triggered,
* NULL);
* }
* ]|
* static void
* my_function ()
* {
* LfbEvent *event = lfb_event_new ("message-new-instant");
* lfb_event_trigger_feedback_async (event, NULL,
* (GAsyncReadyCallback)on_feedback_triggered,
* NULL);
* }
* ```
*/
enum {
@@ -294,7 +294,7 @@ lfb_event_class_init (LfbEventClass *klass)
*
* How long feedback should be provided in seconds. The special value
* %-1 uses the natural length of each feedback while %0 plays each feedback
* in a loop until ended explicitly via e.g. #lfb_event_end_feedback().
* in a loop until ended explicitly via e.g. [method@LfbEvent.end_feedback]().
*/
props[PROP_TIMEOUT] =
g_param_spec_int (
@@ -326,7 +326,7 @@ lfb_event_class_init (LfbEventClass *klass)
* LfbEvent:feedback-profile:
*
* The name of the feedback profile to use for this event. See
* #lfb_event_set_feedback_profile() for details.
* [method@LfbEvent.set_feedback_profile]() for details.
*/
props[PROP_FEEDBACK_PROFILE] =
g_param_spec_string (
@@ -363,10 +363,10 @@ lfb_event_init (LfbEvent *self)
* lfb_event_new:
* @event: The event's name.
*
* Creates a new #LfbEvent based on the given event
* name. See #LfbEvent:event for details.
* Creates a new [class@Lfb.Event] based on the given event
* name. See [property@Lfb.Event:event] for details.
*
* Returns: The #LfbEvent.
* Returns: The [class@Lfb.Event].
*/
LfbEvent *
lfb_event_new (const char *event)
@@ -446,13 +446,13 @@ lfb_event_trigger_feedback (LfbEvent *self, GError **error)
/**
* lfb_event_trigger_feedback_async:
* @self: The event to trigger feedback for.
* @cancellable: (nullable): A #GCancellable or %NULL.
* @cancellable: (nullable): A #GCancellable to cancel the operation or %NULL.
* @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
* @user_data: User data to pass to @callback.
*
* Tells the feedback server to provide proper feedback for the give
* event to the user. This is the sync version of
* #lfb_event_trigger_feedback.
* [method@LfbEvent.trigger_feedback]().
*/
void
lfb_event_trigger_feedback_async (LfbEvent *self,
@@ -494,11 +494,10 @@ lfb_event_trigger_feedback_async (LfbEvent *self,
/**
* lfb_event_trigger_feedback_finish:
* @self: the event
* @res: Result object passed to the callback of
* #lfb_event_trigger_feedback_async
* @res: Result object passed to the callback of [method@LfbEvent.trigger_feedback_async]
* @error: Return location for error
*
* Finish an async operation started by lfb_event_trigger_feedback_async. You
* Finish an async operation started by [method@LfbEvent.trigger_feedback_async](). You
* must call this function in the callback to free memory and receive any
* errors which occurred.
*
@@ -544,8 +543,7 @@ lfb_event_end_feedback (LfbEvent *self, GError **error)
/**
* lfb_event_end_feedback_finish:
* @self: the event
* @res: Result object passed to the callback of
* #lfb_event_end_feedback_async
* @res: Result object passed to the callback of [method@LfbEvent.end_feedback_async]()
* @error: Return location for error
*
* Finish an async operation started by lfb_event_end_feedback_async. You
@@ -553,7 +551,7 @@ lfb_event_end_feedback (LfbEvent *self, GError **error)
* errors which occurred.
*
* This does not mean that the feedbacks finished right away. Connect to the
* #LfbEvent::feedback-ended signal for this.
* [@signal@LfbEvent::feedback-ended] signal for this.
*
* Returns: %TRUE if ending the feedbacks was successful
*/
@@ -570,7 +568,7 @@ lfb_event_end_feedback_finish (LfbEvent *self,
/**
* lfb_event_end_feedback_async:
* @self: The event to end feedback for.
* @cancellable: (nullable): A #GCancellable or %NULL.
* @cancellable: (nullable): A #GCancellable to cancel the operation or %NULL.
* @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
* @user_data: User data to pass to @callback.
*
@@ -611,10 +609,10 @@ lfb_event_end_feedback_async (LfbEvent *self,
* Tells the feedback server to end feedack after #timeout seconds.
* The value -1 indicates to not set a timeout and let feedbacks stop
* on their own while 0 indicates to loop all feedbacks endlessly.
* They must be stopped via #lfb_event_end_feedback () in this case.
* They must be stopped via [method@LfbEvent.end_feedback]() in this case.
*
* It is an error to change the timeout after the feedback has been triggered
* via lfb_event_trigger.
* via [method@LfbEvent.trigger_feedback]().
*/
void
lfb_event_set_timeout (LfbEvent *self, gint timeout)
@@ -649,7 +647,7 @@ lfb_event_get_event (LfbEvent *self)
*
* Get the currently set timeout.
*
* Returns: The event timeout in msecs
* Returns: The event timeout in milliseconds
*/
gint
lfb_event_get_timeout (LfbEvent *self)
libfeedback/libfeedback.c
+3 -29
View File
@@ -9,34 +9,6 @@
#include "lfb-names.h"
/**
* SECTION:libfeedback
* @Short_description: Library initialization and helpers
* @Title: libfeedback
*
* To use the library call #lfb_init() with the id of your application
* (usually the desktop file name without the .desktop extension).
* After initializing the library you can trigger feedback using
* #LfbEvent objects. When your application finishes call
* #lfb_uninit() to free any resources:
*
* |[<!-- language="C" -->
* #define LIBFEEDBACK_USE_UNSTABLE_API
* #include <libfeedback.h>
*
* int main(void)
* {
* g_autoptr (GError) *err = NULL;
* if (lfb_init ("com.example.appid", &err)) {
* g_error ("%s", err->message);
* }
* ...
* lfb_uninit ();
* return 0;
* }
* ]|
*/
static LfbGdbusFeedback *_proxy;
static char *_app_id;
static gboolean _initted;
@@ -99,7 +71,7 @@ _lfb_get_proxy (void)
* @app_id: The application id
* @error: Error information
*
* Initialize libfeedback. This must be called before any other functions.
* Initialize libfeedback. This must be called before any other of libfeedback's functions.
*
* Returns: %TRUE if successful, or %FALSE on error.
*/
@@ -159,6 +131,8 @@ lfb_set_app_id (const char *app_id)
/**
* lfb_get_app_id:
*
* Get the application id set via [func@Lfb.set_app_id]().
*
* Returns: the application id.
*/
const gchar *
meson.build
+1 -1
View File
@@ -1,7 +1,7 @@
project('feedbackd', 'c',
version : '0.0.1',
license : 'LGPLv3+',
meson_version : '>= 0.49.0',
meson_version : '>= 0.56.0',
default_options : [
'warning_level=1',
'buildtype=debugoptimized',
tests/meson.build
+1 -1
View File
@@ -5,7 +5,7 @@ test_env.set('G_TEST_SRCDIR', meson.current_source_dir())
test_env.set('G_TEST_BUILDDIR', meson.current_build_dir())
test_env.set('G_DEBUG', 'gc-friendly,fatal-warnings')
test_env.set('GSETTINGS_BACKEND', 'memory')
test_env.set('GSETTINGS_SCHEMA_DIR', '@0@/data'.format(meson.build_root()))
test_env.set('GSETTINGS_SCHEMA_DIR', '@0@/data'.format(meson.project_build_root()))
test_env.set('PYTHONDONTWRITEBYTECODE', 'yes')
test_env.set('MALLOC_CHECK_', '2')
test_env.set('XDG_CONFIG_HOME', meson.current_source_dir())
tests/services/meson.build
+1 -1
View File
@@ -1,6 +1,6 @@
service_file = 'org.sigxcpu.Feedback.service'
service_data = configuration_data()
service_data.set('ABS_BUILDDIR', meson.build_root())
service_data.set('ABS_BUILDDIR', meson.project_build_root())
configure_file(
input : service_file + '.in',