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

Switch library documentation to gi-docgen

Browse Source 
Switch from gtk-doc to gi-docgen for the library documentation and
adjust the source files accordingly.

We don't bother about the daemon doc headers as they're not built into
any docs atm.

Closes: #56
This commit is contained in:
Guido Günther
2022-12-06 12:44:54 +01:00
parent 7b7422f98e
commit a150c2cbc3
14 changed files with 257 additions and 319 deletions
Download Patch File Download Diff File Expand all files Collapse all files
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 *