docs: api: Replace hotdoc specific commands with Doxygen specific commands

2021-05-13 17:54:58 +03:00
parent 89549247f8
commit d692f06f0d
90 changed files with 4716 additions and 2766 deletions
--- a/lib/wp/transition.c
+++ b/lib/wp/transition.c
@@ -6,17 +6,22 @@
 * SPDX-License-Identifier: MIT
 */

-/**
- * SECTION: transition
- * @title: Transitions
+/*!
+ * @file transition.c
+ */
+
+/*!
+ * @struct WpTransition
+ * @section transition_section Transitions
 *
- * A transition is an asynchronous operation, like #GTask, that contains
- * an internal state machine, where a series of 'steps' are executed in order
- * to complete the operation.
+ * A transition is an asynchronous operation, like
+ * <a href="https://developer.gnome.org/gio/stable/GTask.html">
+ * GTask</a>, that contains an internal state machine,
+ * where a series of 'steps' are executed in order to complete the operation.
 *
- * For every step, #WpTransitionClass.get_next_step() is called in order to
- * determine the next step to execute. Afterwards,
- * #WpTransitionClass.execute_step() is called
+ * For every step, [WpTransitionClass](@ref transition_class_section).get_next_step()
+ * is called in order to determine the next step to execute. Afterwards,
+ * [WpTransitionClass](@ref transition_class_section).execute_step() is called
 * to perform any actions necessary to complete this step. When execution
 * of the step is done, the operation's code must call wp_transition_advance()
 * in order to continue to the next step. If an error occurs, the operation's
@@ -24,11 +29,13 @@
 * transition completes immediately and wp_transition_had_error() returns %TRUE.
 *
 * Typically, every step will start an asynchronous operation. Although is is
- * possible, the #WpTransition base class does not expect
- * #WpTransitionClass.execute_step() to call wp_transition_advance() directly.
+ * possible, the [WpTransition](@ref transition_section) base class does not expect
+ * [WpTransitionClass](@ref transition_class_section).execute_step()
+ * to call wp_transition_advance() directly.
 * Instead, it is expected that wp_transition_advance() will be called from
 * the callback that the step's asyncrhonous operation will call when it is
 * completed.
+ *
 */

 #define G_LOG_DOMAIN "wp-transition"
@@ -57,6 +64,18 @@ struct _WpTransitionPrivate
  GError *error;
 };

+/*!
+ * @memberof WpTransition
+ *
+ * @props @b completed
+ *
+ * @code
+ * "completed" gboolean
+ * @endcode
+ *
+ * Flags : Read
+ *
+ */
 enum {
  PROP_0,
  PROP_COMPLETED,
@@ -114,10 +133,10 @@ wp_transition_class_init (WpTransitionClass * klass)
  object_class->finalize = wp_transition_finalize;
  object_class->get_property = wp_transition_get_property;

-  /**
+  /*
   * WpTransition::completed:
   *
-   * Whether the transition has completed, meaning its callback (if set)
+   * @brief Whether the transition has completed, meaning its callback (if set)
   * has been invoked. This can only happen after the final step has been
   * reached or wp_transition_return_error() has been called.
   *
@@ -150,27 +169,37 @@ wp_transition_async_result_init (GAsyncResultIface * iface)
      (gboolean (*)(GAsyncResult *, gpointer)) wp_transition_is_tagged;
 }

-/**
- * wp_transition_new:
- * @type: the #GType of the #WpTransition subclass to instantiate
- * @source_object: (nullable) (type GObject): the #GObject that owns this task,
- *   or %NULL
- * @cancellable: (nullable): optional #GCancellable
- * @callback: (scope async): a #GAsyncReadyCallback
- * @callback_data: (closure): user data passed to @callback
+/*!
 *
- * Creates a #WpTransition acting on @source_object. When the transition is
- * done, @callback will be invoked.
+ * @memberof WpTransition
+ *
+ * @param type: the
+ * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
+ * GType</a> of the [WpTransition](@ref transition_section) subclass to instantiate
+ * @param source_object: (nullable) (type GObject): the
+ * <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject">
+ * GObject</a> that owns this task, or %NULL
+ * @param cancellable: (nullable): optional
+ * <a href="https://developer.gnome.org/gio/stable/GCancellable.html">
+ * GCancellable</a>
+ * @param callback: (scope async): a
+ * <a href="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncReadyCallback">
+ * GAsyncReadyCallback</a>
+ * @param callback_data: (closure): user data passed to @em callback
+ *
+ * @brief Creates a [WpTransition](@ref transition_section) acting on @em source_object. When the transition is
+ * done, @em callback will be invoked.
 *
 * The transition does not automatically start executing steps. You must
 * call wp_transition_advance() after creating it in order to start it.
 *
- * Note that the transition is automatically unref'ed after the @callback
+ * Note that the transition is automatically unref'ed after the @em callback
 * has been executed. If you wish to keep an additional reference on it,
 * you need to ref it explicitly.
 *
- * Returns: (transfer none): the new transition
+ * @returns (transfer none): the new transition
 */
+
 WpTransition *
 wp_transition_new (GType type,
    gpointer source_object, GCancellable * cancellable,
@@ -180,26 +209,37 @@ wp_transition_new (GType type,
      g_cclosure_new (G_CALLBACK (callback), callback_data, NULL));
 }

-/**
- * wp_transition_new_closure:
- * @type: the #GType of the #WpTransition subclass to instantiate
- * @source_object: (nullable) (type GObject): the #GObject that owns this task,
- *   or %NULL
- * @cancellable: (nullable): optional #GCancellable
- * @closure: (nullable): a #GAsyncReadyCallback wrapped in a #GClosure
+/*!
+ * @memberof WpTransition
+ * @param type: the
+ * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
+ * GType</a>
+ * of the [WpTransition](@ref transition_section) subclass to instantiate
+ * @param source_object: (nullable) (type GObject): the
+ * <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject">
+ * GObject</a> that owns this task, or %NULL
+ * @param cancellable: (nullable): optional
+ * <a href="https://developer.gnome.org/gio/stable/GCancellable.html">
+ * GCancellable</a>
+ * @param closure: (nullable): a
+ * <a href="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncReadyCallback">
+ * GAsyncReadyCallback</a> wrapped in a
+ * <a href="https://developer.gnome.org/gobject/stable/gobject-Closures.html#GClosure">
+ * GClosure</a>
 *
- * Creates a #WpTransition acting on @source_object. When the transition is
- * done, @closure will be invoked.
+ * @brief Creates a [WpTransition](@ref transition_section) acting on @em source_object.
+ * When the transition is done, @em closure will be invoked.
 *
 * The transition does not automatically start executing steps. You must
 * call wp_transition_advance() after creating it in order to start it.
 *
- * Note that the transition is automatically unref'ed after the @closure
+ * Note that the transition is automatically unref'ed after the @em closure
 * has been executed. If you wish to keep an additional reference on it,
 * you need to ref it explicitly.
 *
- * Returns: (transfer none): the new transition
+ * @returns (transfer none): the new transition
 */
+
 WpTransition *
 wp_transition_new_closure (GType type, gpointer source_object,
    GCancellable * cancellable, GClosure * closure)
@@ -223,15 +263,16 @@ wp_transition_new_closure (GType type, gpointer source_object,
  return self;
 }

-/**
- * wp_transition_get_source_object:
- * @self: the transition
+/*!
+ * @memberof WpTransition
+ * @param self: the transition
 *
- * Gets the source object from the transition.
+ * @brief Gets the source object from the transition.
 * Like g_async_result_get_source_object(), but does not ref the object.
 *
- * Returns: (transfer none) (type GObject): the source object
+ * @returns (transfer none) (type GObject): the source object
 */
+
 gpointer
 wp_transition_get_source_object (WpTransition * self)
 {
@@ -241,16 +282,17 @@ wp_transition_get_source_object (WpTransition * self)
  return priv->source_object;
 }

-/**
- * wp_transition_is_tagged:
- * @self: the transition
- * @tag: a tag
+/*!
+ * @memberof WpTransition
+ * @param self: the transition
+ * @param tag: a tag
 *
- * Checks if @self has the given @tag (generally a function pointer
- * indicating the function @self was created by).
+ * @brief Checks if @em self has the given @em tag (generally a function pointer
+ * indicating the function @em self was created by).
 *
- * Returns: TRUE if @self has the indicated @tag , FALSE if not.
+ * @returns TRUE if @em self has the indicated @em tag , FALSE if not.
 */
+
 gboolean
 wp_transition_is_tagged (WpTransition * self, gpointer tag)
 {
@@ -260,14 +302,15 @@ wp_transition_is_tagged (WpTransition * self, gpointer tag)
  return (priv->tag == tag);
 }

-/**
- * wp_transition_get_source_tag:
- * @self: the transition
+/*!
+ * @memberof WpTransition
+ * @param self: the transition
 *
- * Gets @self 's source tag. See wp_transition_set_source_tag().
+ * @brief Gets @em self 's source tag. See wp_transition_set_source_tag().
 *
- * Returns: (transfer none): the transition's source tag
+ * @returns (transfer none): the transition's source tag
 */
+
 gpointer
 wp_transition_get_source_tag (WpTransition * self)
 {
@@ -277,17 +320,18 @@ wp_transition_get_source_tag (WpTransition * self)
  return priv->tag;
 }

-/**
- * wp_transition_set_source_tag:
- * @self: the transition
- * @tag: an opaque pointer indicating the source of this transition
+/*!
+ * @memberof WpTransition
+ * @param self: the transition
+ * @param tag: an opaque pointer indicating the source of this transition
 *
- * Sets @self 's source tag. You can use this to tag a transition's return
+ * @brief Sets @em self 's source tag. You can use this to tag a transition's return
 * value with a particular pointer (usually a pointer to the function doing
 * the tagging) and then later check it using wp_transition_get_source_tag()
 * (or g_async_result_is_tagged()) in the transition's "finish" function,
 * to figure out if the response came from a particular place.
 */
+
 void
 wp_transition_set_source_tag (WpTransition * self, gpointer tag)
 {
@@ -297,14 +341,15 @@ wp_transition_set_source_tag (WpTransition * self, gpointer tag)
  priv->tag = tag;
 }

-/**
- * wp_transition_get_data:
- * @self: the transition
+/*!
+ * @memberof WpTransition
+ * @param self: the transition
 *
- * Gets @self 's data. See wp_transition_set_data().
+ * @brief Gets @em self 's data. See wp_transition_set_data().
 *
- * Returns: (transfer none): the transition's data
+ * @returns (transfer none): the transition's data
 */
+
 gpointer
 wp_transition_get_data (WpTransition * self)
 {
@@ -314,15 +359,19 @@ wp_transition_get_data (WpTransition * self)
  return priv->data;
 }

-/**
- * wp_transition_set_data:
- * @self: the transition
- * @data: (nullable): transition-specific user data
- * @data_destroy: (nullable): #GDestroyNotify for @data
+/*!
+ * @memberof WpTransition
+ * @param self: the transition
+ * @param data: (nullable): transition-specific user data
+ * @param data_destroy: (nullable):
+ * <a href="https://developer.gnome.org/glib/stable/glib-Datasets.html#GDestroyNotify">
+ * GDestroyNotify</a>
+ * for @em data
 *
- * Sets @self 's data (freeing the existing data, if any). This can be an
+ * @brief Sets @em self 's data (freeing the existing data, if any). This can be an
 * arbitrary user structure that holds data associated with this transition.
 */
+
 void
 wp_transition_set_data (WpTransition * self, gpointer data,
    GDestroyNotify data_destroy)
@@ -336,13 +385,14 @@ wp_transition_set_data (WpTransition * self, gpointer data,
  priv->data_destroy = data_destroy;
 }

-/**
- * wp_transition_get_completed:
- * @self: the transition
+/*!
+ * @memberof WpTransition
+ * @param self: the transition
 *
- * Returns: %TRUE if the transition has completed (with or without an error),
+ * @returns %TRUE if the transition has completed (with or without an error),
 *   %FALSE otherwise
 */
+
 gboolean
 wp_transition_get_completed (WpTransition * self)
 {
@@ -353,12 +403,13 @@ wp_transition_get_completed (WpTransition * self)
         priv->step == WP_TRANSITION_STEP_ERROR;
 }

-/**
- * wp_transition_had_error:
- * @self: the transition
+/*!
+ * @memberof WpTransition
+ * @param self: the transition
 *
- * Returns: %TRUE if the transition completed with an error, %FALSE otherwise
+ * @returns %TRUE if the transition completed with an error, %FALSE otherwise
 */
+
 gboolean
 wp_transition_had_error (WpTransition * self)
 {
@@ -388,32 +439,35 @@ wp_transition_return (WpTransition * self, WpTransitionPrivate *priv)
  g_object_unref (self);
 }

-/**
- * wp_transition_advance:
- * @self: the transition
+/*!
+ * @memberof WpTransition
+ * @param self: the transition
 *
- * Advances the transition to the next step.
+ * @brief Advances the transition to the next step.
 *
- * This initially calls #WpTransitionClass.get_next_step() in order to determine
- * what the next step is. If #WpTransitionClass.get_next_step() returns a step
- * different than the previous one, it calls #WpTransitionClass.execute_step()
- * to execute it.
+ * This initially calls [WpTransitionClass](@ref transition_class_section).get_next_step()
+ * in order to determine what the next step is.
+ * If [WpTransitionClass](@ref transition_class_section).get_next_step() returns a step
+ * different than the previous one, it calls
+ * [WpTransitionClass](@ref transition_class_section).execute_step() to execute it.
 *
- * The very first time that #WpTransitionClass.get_next_step() is called, its
- * @step parameter equals %WP_TRANSITION_STEP_NONE.
+ * The very first time that [WpTransitionClass](@ref transition_class_section).get_next_step()
+ * is called, its @em step parameter equals %WP_TRANSITION_STEP_NONE.
 *
- * When #WpTransitionClass.get_next_step() returns %WP_TRANSITION_STEP_NONE,
- * this function completes the transition, calling the transition's callback
- * and then unref-ing the transition.
+ * When [WpTransitionClass](@ref transition_class_section).get_next_step() returns
+ * %WP_TRANSITION_STEP_NONE this function completes the transition, calling the transition's
+ * callback and then unref-ing the transition.
 *
- * When #WpTransitionClass.get_next_step() returns %WP_TRANSITION_STEP_ERROR,
- * this function calls wp_transition_return_error(), unless it has already been
- * called directly by #WpTransitionClass.get_next_step().
+ * When [WpTransitionClass](@ref transition_class_section).get_next_step() returns
+ * %WP_TRANSITION_STEP_ERROR, this function calls wp_transition_return_error(),
+ * unless it has already been called directly by
+ * [WpTransitionClass](@ref transition_class_section).get_next_step().
 *
- * In error conditions, #WpTransitionClass.execute_step() is called once with
- * @step being %WP_TRANSITION_STEP_ERROR, allowing the implementation to
+ * In error conditions, [WpTransitionClass](@ref transition_class_section).execute_step()
+ * is called once with @em step being %WP_TRANSITION_STEP_ERROR, allowing the implementation to
 * rollback any changes or cancel underlying jobs, if necessary.
 */
+
 void
 wp_transition_advance (WpTransition * self)
 {
@@ -465,17 +519,20 @@ wp_transition_advance (WpTransition * self)
  WP_TRANSITION_GET_CLASS (self)->execute_step (self, priv->step);
 }

-/**
- * wp_transition_return_error:
- * @self: the transition
- * @error: (transfer full): a #GError
+/*!
+ * @memberof WpTransition
+ * @param self: the transition
+ * @param error: (transfer full): a
+ * <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
+ * GError</a>
 *
- * Completes the transition with an error. This can be called anytime
+ * @brief Completes the transition with an error. This can be called anytime
 * from within any virtual function or an async job handler.
 *
 * Note that in most cases this will also unref the transition, so it is
 * not safe to access it after this function has been called.
 */
+
 void
 wp_transition_return_error (WpTransition * self, GError * error)
 {
@@ -499,18 +556,23 @@ wp_transition_return_error (WpTransition * self, GError * error)
  wp_transition_return (self, priv);
 }

-/**
- * wp_transition_finish:
- * @res: a transition, as a #GAsyncResult
- * @error: (out) (optional): a location to return the transition's error, if any
+/*!
+ * @memberof WpTransition
+ * @param res: a transition, as a
+ * <a href="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncResult-struct">
+ * GAsyncResult</a>
+ * @param error: (out) (optional): a location to return the transition's error, if any
 *
- * This is meant to be called from within the #GAsyncReadyCallback that was
- * specified in wp_transition_new(). It returns the final return status
+ * @brief This is meant to be called from within the
+ * <a herf="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncReadyCallback">
+ * GAsyncReadyCallback</a>
+ * that was specified in wp_transition_new(). It returns the final return status
 * of the transition and its error, if there was one.
 *
- * Returns: %TRUE if the transition completed successfully, %FALSE if there
+ * @returns %TRUE if the transition completed successfully, %FALSE if there
 *   was an error
 */
+
 gboolean
 wp_transition_finish (GAsyncResult * res, GError ** error)
 {
@@ -527,4 +589,4 @@ wp_transition_finish (GAsyncResult * res, GError ** error)
      (priv->step == WP_TRANSITION_STEP_NONE) ? "ok" : "with error");

  return (priv->step == WP_TRANSITION_STEP_NONE);
-}
+}