[tepl] docs: document important detail about static objects in Amtk

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

commit 1a1dee57727729ab6616da5a4da57ae981fcbc31
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Aug 6 13:58:46 2017 +0200

    docs: document important detail about static objects in Amtk

 amtk/amtk-action-info-store.c |    5 +++++
 amtk/amtk-factory.c           |   11 +++++++++++
 2 files changed, 16 insertions(+), 0 deletions(-)
---
diff --git a/amtk/amtk-action-info-store.c b/amtk/amtk-action-info-store.c
index a215aee..0308af2 100644
--- a/amtk/amtk-action-info-store.c
+++ b/amtk/amtk-action-info-store.c
@@ -38,6 +38,11 @@
  * conflicts when an #AmtkActionInfo is added to the
  * #AmtkActionInfoCentralStore. Examples of namespaced action names:
  * `"win.amtk-save"` or `"app.amtk-quit"`.
+ *
+ * Once an #AmtkActionInfo has been added to an #AmtkActionInfoStore, it is
+ * discouraged to modify it afterwards. An #AmtkActionInfoStore is meant to be
+ * something static, created on application startup. See the [paragraph about
+ * static objects in AmtkFactory][amtk-factory-static-objects].
  */
 
 struct _AmtkActionInfoStorePrivate
diff --git a/amtk/amtk-factory.c b/amtk/amtk-factory.c
index 437fecb..54b6b4e 100644
--- a/amtk/amtk-factory.c
+++ b/amtk/amtk-factory.c
@@ -45,6 +45,17 @@
  * #AmtkFactory:default-flags. See for example
  * amtk_factory_menu_create_menu_item() and
  * amtk_factory_menu_create_menu_item_full().
+ *
+ * # Static objects # {#amtk-factory-static-objects}
+ *
+ * An important detail is that once a factory function has created an object,
+ * the object is not updated if the corresponding #AmtkActionInfo is modified
+ * afterwards. #AmtkActionInfo doesn't have a notify signal, and it is anyway
+ * discouraged to modify an #AmtkActionInfo after being added to an
+ * #AmtkActionInfoStore. An #AmtkActionInfoStore is meant to be something
+ * static, created on application startup. Updating automatically menu and
+ * toolbar items is out of scope for the Amtk library. If for example action
+ * accelerators can be modified at run-time, the menu needs to be re-generated.
  */
 
 struct _AmtkFactoryPrivate