[tepl] Amtk: fix/improve doc

[Sébastien Wilmet <swilmet src gnome org>]

commit 5ac2a7c6354a666d733373077bc33f75510eafe0
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Mon Jul 17 21:33:59 2017 +0200

    Amtk: fix/improve doc

 amtk/amtk-action-info.c  |    4 ++++
 amtk/amtk-action-info.h  |    2 +-
 amtk/amtk-factory-menu.c |   22 ++++++++--------------
 amtk/amtk-factory.c      |   27 ++++++++++++++++++++++-----
 amtk/amtk-factory.h      |    3 +++
 5 files changed, 38 insertions(+), 20 deletions(-)
---
diff --git a/amtk/amtk-action-info.c b/amtk/amtk-action-info.c
index 1f5dea1..fd61736 100644
--- a/amtk/amtk-action-info.c
+++ b/amtk/amtk-action-info.c
@@ -284,6 +284,8 @@ amtk_action_info_set_icon_name (AmtkActionInfo *info,
  * amtk_action_info_get_label:
  * @info: an #AmtkActionInfo.
  *
+ * Gets the label. The label has normally a mnemonic.
+ *
  * Returns: (nullable): the label (i.e. a short description), or %NULL.
  * Since: 2.0
  */
@@ -300,6 +302,8 @@ amtk_action_info_get_label (const AmtkActionInfo *info)
  * @info: an #AmtkActionInfo.
  * @label: (nullable): the label (i.e. a short description), or %NULL.
  *
+ * Sets the label with a mnemonic.
+ *
  * Since: 2.0
  */
 void
diff --git a/amtk/amtk-action-info.h b/amtk/amtk-action-info.h
index a0eb0e0..18058ca 100644
--- a/amtk/amtk-action-info.h
+++ b/amtk/amtk-action-info.h
@@ -35,7 +35,7 @@ G_BEGIN_DECLS
  * AmtkActionInfoEntry:
  * @action_name: the action name.
  * @icon_name: the icon name, or %NULL.
- * @label: the label (i.e. a short description), or %NULL.
+ * @label: the label (i.e. a short description) with a mnemonic, or %NULL.
  * @accel: the accelerator, in the format understood by gtk_accelerator_parse().
  * Or %NULL.
  * @tooltip: the tooltip (i.e. a long description), or %NULL.
diff --git a/amtk/amtk-factory-menu.c b/amtk/amtk-factory-menu.c
index f481341..fbb36c2 100644
--- a/amtk/amtk-factory-menu.c
+++ b/amtk/amtk-factory-menu.c
@@ -28,6 +28,14 @@
  * @Title: AmtkFactoryMenu
  *
  * #AmtkFactoryMenu permits to create #GtkMenuItem's from #AmtkActionInfo's.
+ *
+ * If not ignored by an #AmtkFactoryFlags, the first accelerator returned by
+ * amtk_action_info_get_accels() is set to the #GtkAccelLabel of the
+ * #GtkMenuItem.
+ *
+ * If not ignored by an #AmtkFactoryFlags, the tooltip is set with
+ * amtk_menu_item_set_long_description(), which permits to display it in a
+ * #GtkStatusbar with amtk_application_window_connect_menu_to_statusbar().
  */
 
 struct _AmtkFactoryMenuPrivate
@@ -91,20 +99,6 @@ amtk_factory_menu_new_with_default_application (void)
  * Creates a new #GtkMenuItem for @action_name with the
  * #AmtkFactory:default-flags.
  *
- * The #AmtkActionInfoCentralStore must contain an #AmtkActionInfo for
- * @action_name.
- *
- * gtk_actionable_set_action_name() is called on the menu item with
- * @action_name. The label is set with the #GtkMenuItem:use-underline property
- * enabled. The first accelerator is set to the #GtkAccelLabel of the menu item.
- * The icon is set. And the tooltip is set with
- * amtk_menu_item_set_long_description().
- *
- * If the #AmtkFactory:application is non-%NULL, this function also calls
- * gtk_application_set_accels_for_action() with the accelerators returned by
- * amtk_action_info_get_accels() (this will erase previously set accelerators
- * for that action, if any).
- *
  * Returns: (transfer floating): a new #GtkMenuItem for @action_name.
  * Since: 3.0
  */
diff --git a/amtk/amtk-factory.c b/amtk/amtk-factory.c
index c444224..f7646b4 100644
--- a/amtk/amtk-factory.c
+++ b/amtk/amtk-factory.c
@@ -25,13 +25,30 @@
  * @Short_description: Factory base class
  * @Title: AmtkFactory
  *
- * #AmtkFactory is a base class to create #GtkWidget's from #AmtkActionInfo's.
+ * #AmtkFactory is a base class to create menu or toolbar items (or anything
+ * else) from #AmtkActionInfo's. A factory function accesses an #AmtkActionInfo
+ * from the #AmtkActionInfoCentralStore.
  *
- * A #GtkApplication can be associated so that when a widget is created,
- * gtk_application_set_accels_for_action() is called.
+ * A #GtkApplication can be associated so that factory functions can call
+ * gtk_application_set_accels_for_action() with the accelerators returned by
+ * amtk_action_info_get_accels() (this erases previously set accelerators for
+ * that action, if any). Note that gtk_application_set_accels_for_action() is
+ * called by factory functions and not by amtk_action_info_store_add(), so that
+ * libraries can provide their own store and the accelerators are set to the
+ * #GtkApplication only if an #AmtkActionInfo is actually used.
  *
- * Once the widgets are created, an #AmtkFactory should be freed because it has
- * a strong reference to the #GtkApplication.
+ * #AmtkFactoryFlags permits to control how a factory function creates the
+ * object, to ignore some steps. Factory functions should be declined in two
+ * variants: a simple form which takes the value of the
+ * #AmtkFactory:default-flags property, and the same function with the `_full`
+ * suffix which takes an #AmtkFactoryFlags argument and ignores the
+ * #AmtkFactory:default-flags. See for example
+ * amtk_factory_menu_create_menu_item() and
+ * amtk_factory_menu_create_menu_item_full().
+ *
+ * Once the objects are created, an #AmtkFactory should be freed because it has
+ * a strong reference to the #GtkApplication. TODO: change it to a weak ref
+ * instead so that this paragraph can be removed.
  */
 
 struct _AmtkFactoryPrivate
diff --git a/amtk/amtk-factory.h b/amtk/amtk-factory.h
index 6a0e92d..c248d3a 100644
--- a/amtk/amtk-factory.h
+++ b/amtk/amtk-factory.h
@@ -65,6 +65,9 @@ struct _AmtkFactoryClass
  * @AMTK_FACTORY_IGNORE_ACCELS_FOR_APP: Do not call
  *   gtk_application_set_accels_for_action().
  *
+ * #AmtkFactoryFlags permits to control how a factory function creates the
+ * object, to ignore some steps.
+ *
  * Since: 3.0
  */
 typedef enum