GNOME.org
 

[tepl] amtk: adapt/improve doc

commit 88e44778a2dbaa7030dfd574dd980e0dfb2fee5f
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Jul 15 15:07:52 2017 +0200

    amtk: adapt/improve doc

 amtk/amtk-action-info-central-store.c |    6 ++--
 amtk/amtk-action-info-store.c         |   37 ++++++++++++++---------------
 amtk/amtk-action-info.c               |   42 +++++++++++++++++---------------
 3 files changed, 43 insertions(+), 42 deletions(-)
---
diff --git a/amtk/amtk-action-info-central-store.c b/amtk/amtk-action-info-central-store.c
index fa3a1d9..6fa7937 100644
--- a/amtk/amtk-action-info-central-store.c
+++ b/amtk/amtk-action-info-central-store.c
@@ -27,7 +27,7 @@
  * @See_also: #AmtkActionInfoStore
  *
  * #AmtkActionInfoCentralStore is a singleton class containing the aggregation
- * of all #AmtkActionInfoStore's. Each time a #AmtkActionInfo is added to a
+ * of all #AmtkActionInfoStore's. Each time an #AmtkActionInfo is added to a
  * #AmtkActionInfoStore, it is also added to the #AmtkActionInfoCentralStore.
  */
 
@@ -126,7 +126,7 @@ _amtk_action_info_central_store_add (AmtkActionInfoCentralStore *central_store,
 
        if (g_hash_table_lookup (central_store->priv->hash_table, action_name) != NULL)
        {
-               g_warning ("The AmtkActionInfoCentralStore already contains a AmtkActionInfo "
+               g_warning ("The AmtkActionInfoCentralStore already contains an AmtkActionInfo "
                           "with the action name “%s”. Libraries must namespace their action names.",
                           action_name);
                return;
@@ -139,7 +139,7 @@ _amtk_action_info_central_store_add (AmtkActionInfoCentralStore *central_store,
 
 /**
  * amtk_action_info_central_store_lookup:
- * @central_store: a #AmtkActionInfoCentralStore.
+ * @central_store: the #AmtkActionInfoCentralStore.
  * @action_name: an action name.
  *
  * Returns: (transfer none): the found #AmtkActionInfo, or %NULL.
diff --git a/amtk/amtk-action-info-store.c b/amtk/amtk-action-info-store.c
index 2758f63..20189a2 100644
--- a/amtk/amtk-action-info-store.c
+++ b/amtk/amtk-action-info-store.c
@@ -36,19 +36,18 @@
  * A #GtkApplication can be associated so that when a widget is created,
  * gtk_application_set_accels_for_action() is called. See
  * amtk_action_info_store_create_menu_item() for more details. Note that this
- * happens on widget creation, not when adding a #AmtkActionInfo to the store,
+ * happens on widget creation, not when adding an #AmtkActionInfo to the store,
  * so that the accelerator is bound to the application only if the
  * #AmtkActionInfo is actually used.
  *
  * #AmtkActionInfoStore is designed so that libraries can provide their own
  * store, to share action information (with translations) and possibly the
- * #GAction implementations as well. Application-specific #AmtkActionInfo's can
- * be added to the store returned by
- * tepl_application_get_app_action_info_store().
+ * #GAction implementations as well.
  *
  * A library #AmtkActionInfoStore must namespace the action names to not have
- * conflicts when a #AmtkActionInfo is added to the #AmtkActionInfoCentralStore.
- * Examples of namespaced action names: `"win.amtk-save"` or `"app.amtk-quit"`.
+ * conflicts when an #AmtkActionInfo is added to the
+ * #AmtkActionInfoCentralStore. Examples of namespaced action names:
+ * `"win.amtk-save"` or `"app.amtk-quit"`.
  */
 
 struct _AmtkActionInfoStorePrivate
@@ -223,7 +222,7 @@ amtk_action_info_store_new (GtkApplication *application)
 
 /**
  * amtk_action_info_store_get_application:
- * @store: a #AmtkActionInfoStore.
+ * @store: an #AmtkActionInfoStore.
  *
  * Returns: (transfer none) (nullable): the associated #GtkApplication, or
  * %NULL.
@@ -238,11 +237,11 @@ amtk_action_info_store_get_application (AmtkActionInfoStore *store)
 
 /**
  * amtk_action_info_store_add:
- * @store: a #AmtkActionInfoStore.
- * @info: a #AmtkActionInfo.
+ * @store: an #AmtkActionInfoStore.
+ * @info: an #AmtkActionInfo.
  *
  * Inserts @info into @store and into the #AmtkActionInfoCentralStore. Both the
- * @store and central store must <emphasis>not</emphasis> already contain a
+ * @store and central store must <emphasis>not</emphasis> already contain an
  * #AmtkActionInfo with the same action name. The stores take their own
  * reference on @info.
  *
@@ -263,7 +262,7 @@ amtk_action_info_store_add (AmtkActionInfoStore *store,
 
        if (g_hash_table_lookup (store->priv->hash_table, action_name) != NULL)
        {
-               g_warning ("%s(): the AmtkActionInfoStore already contains a AmtkActionInfo "
+               g_warning ("%s(): the AmtkActionInfoStore already contains an AmtkActionInfo "
                           "with the action name “%s”.",
                           G_STRFUNC,
                           action_name);
@@ -280,7 +279,7 @@ amtk_action_info_store_add (AmtkActionInfoStore *store,
 
 /**
  * amtk_action_info_store_add_entries:
- * @store: a #AmtkActionInfoStore.
+ * @store: an #AmtkActionInfoStore.
  * @entries: (array length=n_entries) (element-type AmtkActionInfoEntry): a
  * pointer to the first item in an array of #AmtkActionInfoEntry structs.
  * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated.
@@ -319,7 +318,7 @@ amtk_action_info_store_add_entries (AmtkActionInfoStore       *store,
 
 /**
  * amtk_action_info_store_lookup:
- * @store: a #AmtkActionInfoStore.
+ * @store: an #AmtkActionInfoStore.
  * @action_name: an action name.
  *
  * Returns: (transfer none): the found #AmtkActionInfo, or %NULL.
@@ -337,10 +336,10 @@ amtk_action_info_store_lookup (AmtkActionInfoStore *store,
 
 /**
  * amtk_action_info_store_create_menu_item:
- * @store: a #AmtkActionInfoStore.
+ * @store: an #AmtkActionInfoStore.
  * @action_name: an action name.
  *
- * Creates a new #GtkMenuItem for @action_name. The @store must contain a
+ * Creates a new #GtkMenuItem for @action_name. The @store must contain an
  * #AmtkActionInfo for @action_name.
  *
  * gtk_actionable_set_action_name() is called on the menu item with
@@ -452,15 +451,15 @@ check_used_cb (gpointer key,
 
 /**
  * amtk_action_info_store_check_all_used:
- * @store: a #AmtkActionInfoStore.
+ * @store: an #AmtkActionInfoStore.
  *
  * Checks that all #AmtkActionInfo's of @store have been used by
  * amtk_action_info_store_create_menu_item(). If not, a warning is printed and
  * might indicate dead code.
  *
- * You probably want to call this function on the store returned by
- * tepl_application_get_app_action_info_store(). But it can also be useful for a
- * store provided by a library, to easily see which actions you don't use.
+ * You probably want to call this function on the application store. But it can
+ * also be useful for a store provided by a library, to easily see which actions
+ * you don't use.
  *
  * Since: 2.0
  */
diff --git a/amtk/amtk-action-info.c b/amtk/amtk-action-info.c
index 0454421..92accd3 100644
--- a/amtk/amtk-action-info.c
+++ b/amtk/amtk-action-info.c
@@ -28,16 +28,18 @@
  * @Title: AmtkActionInfo
  * @See_also: #AmtkActionInfoStore
  *
- * A #AmtkActionInfo instance contains a set of information about a #GAction.
+ * An #AmtkActionInfo instance contains a set of information about a #GAction.
  * Those pieces of information are useful to create UI elements that trigger the
  * #GAction, for example a menu item or a toolbar item.
  *
  * When writing an XML file to create a #GMenu, with the format understood by
  * #GtkBuilder (see the class description of #GtkApplicationWindow), the
- * information in the XML file can be used only to create a #GMenu. The initial
- * goal with #AmtkActionInfo and its related classes is to encode the
- * information just once, and be able to create both a menu and a toolbar easily
- * (to have a traditional user interface).
+ * information in the XML file can be used only to create a #GMenu, not a
+ * toolbar. The initial goal with #AmtkActionInfo and its related classes is to
+ * encode the information just once, and be able to create both a menu and a
+ * toolbar easily (to have a traditional user interface, not based on
+ * #GtkHeaderBar). Note that with the Amtk API, it would also be possible to
+ * create a #GMenu.
  */
 
 struct _AmtkActionInfo
@@ -99,10 +101,10 @@ amtk_action_info_new (void)
 
 /**
  * amtk_action_info_new_from_entry:
- * @info_entry: a #AmtkActionInfoEntry.
+ * @info_entry: an #AmtkActionInfoEntry.
  * @translation_domain: (nullable): a gettext domain, or %NULL.
  *
- * Creates a new #AmtkActionInfo from a #AmtkActionInfoEntry.
+ * Creates a new #AmtkActionInfo from an #AmtkActionInfoEntry.
  *
  * If @translation_domain is not %NULL, g_dgettext() is used to translate the
  * @label and @tooltip before setting them to the #AmtkActionInfo.
@@ -145,7 +147,7 @@ amtk_action_info_new_from_entry (const AmtkActionInfoEntry *info_entry,
 
 /**
  * amtk_action_info_ref:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  *
  * Increments the reference count of @info by one.
  *
@@ -164,7 +166,7 @@ amtk_action_info_ref (AmtkActionInfo *info)
 
 /**
  * amtk_action_info_unref:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  *
  * Decrements the reference count of @info by one. If the reference count drops
  * to 0, @info is freed.
@@ -186,7 +188,7 @@ amtk_action_info_unref (AmtkActionInfo *info)
 
 /**
  * amtk_action_info_copy:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  *
  * Returns: (transfer full): a copy of @info. The copy will have a reference
  * count of one.
@@ -213,7 +215,7 @@ amtk_action_info_copy (const AmtkActionInfo *info)
 
 /**
  * amtk_action_info_get_action_name:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  *
  * Returns: (nullable): the action name, or %NULL. Example: `"win.save"`.
  * Since: 2.0
@@ -228,7 +230,7 @@ amtk_action_info_get_action_name (const AmtkActionInfo *info)
 
 /**
  * amtk_action_info_set_action_name:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  * @action_name: the action name.
  *
  * Sets the action name, for example `"win.save"`.
@@ -248,7 +250,7 @@ amtk_action_info_set_action_name (AmtkActionInfo *info,
 
 /**
  * amtk_action_info_get_icon_name:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  *
  * Returns: (nullable): the icon name, or %NULL.
  * Since: 2.0
@@ -263,7 +265,7 @@ amtk_action_info_get_icon_name (const AmtkActionInfo *info)
 
 /**
  * amtk_action_info_set_icon_name:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  * @icon_name: (nullable): the icon name, or %NULL.
  *
  * Since: 2.0
@@ -280,7 +282,7 @@ amtk_action_info_set_icon_name (AmtkActionInfo *info,
 
 /**
  * amtk_action_info_get_label:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  *
  * Returns: (nullable): the label (i.e. a short description), or %NULL.
  * Since: 2.0
@@ -295,7 +297,7 @@ amtk_action_info_get_label (const AmtkActionInfo *info)
 
 /**
  * amtk_action_info_set_label:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  * @label: (nullable): the label (i.e. a short description), or %NULL.
  *
  * Since: 2.0
@@ -312,7 +314,7 @@ amtk_action_info_set_label (AmtkActionInfo *info,
 
 /**
  * amtk_action_info_get_tooltip:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  *
  * Returns: (nullable): the tooltip (i.e. a long description), or %NULL.
  * Since: 2.0
@@ -327,7 +329,7 @@ amtk_action_info_get_tooltip (const AmtkActionInfo *info)
 
 /**
  * amtk_action_info_set_tooltip:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  * @tooltip: (nullable): the tooltip (i.e. a long description), or %NULL.
  *
  * Since: 2.0
@@ -344,7 +346,7 @@ amtk_action_info_set_tooltip (AmtkActionInfo *info,
 
 /**
  * amtk_action_info_get_accels:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  *
  * Returns the accelerators. This function never returns %NULL, it always
  * returns a %NULL-terminated array, to be suitable for
@@ -366,7 +368,7 @@ amtk_action_info_get_accels (const AmtkActionInfo *info)
 
 /**
  * amtk_action_info_set_accels:
- * @info: a #AmtkActionInfo.
+ * @info: an #AmtkActionInfo.
  * @accels: (array zero-terminated=1): a %NULL-terminated array of accelerators
  * in the format understood by gtk_accelerator_parse().
  *
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]