[gimp] app: add some doc comment to internal API.

[Jehan <jehanp src gnome org>]

commit 6955db425ee7a67a75b4fcd23fdba15f2424d41c
Author: Jehan <jehan girinstud io>
Date:   Wed Feb 2 22:42:03 2022 +0100

    app: add some doc comment to internal API.
    
    Relative to the MR !553 where I could verify that the function
    gimp_tool_push_status() does not just push new messages, it also removes
    any other message from the same context (and place the new one on
    front, unlike gimp_tool_replace_status()).
    
    Therefore calling gimp_tool_pop_status() before a push or replace is
    simply wrong with undesirable effect (e.g. too many useless redraws,
    which can be pretty bad on some platforms like macOS, but are not ideal
    anyway as a general rule).

 app/tools/gimptool.c | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
---
diff --git a/app/tools/gimptool.c b/app/tools/gimptool.c
index 0ad73e1ee1..94b4843539 100644
--- a/app/tools/gimptool.c
+++ b/app/tools/gimptool.c
@@ -1300,6 +1300,26 @@ gimp_tool_get_popup (GimpTool         *tool,
                                                 ui_path);
 }
 
+/*
+ * gimp_tool_push_status:
+ * @tool:
+ * @display:
+ * @format:
+ *
+ * Push a new status message for the context of the @tool, in the shell
+ * associated to @display. Note that the message will replace any
+ * message for the same context (i.e. same tool) while also ensuring it
+ * is in the front of the message list (except for any progress or
+ * temporary messages which might be going on and are always front).
+ * This is the main difference with gimp_tool_replace_status() which
+ * does not necessarily try to make it a front message.
+ *
+ * In particular, it means you don't have to call gimp_tool_pop_status()
+ * first before calling gimp_tool_push_status(). Even more, you should
+ * not pop the status if you were planning to push a new status for the
+ * same context because you are triggering non necessary redraws of the
+ * status bar.
+ */
 void
 gimp_tool_push_status (GimpTool    *tool,
                        GimpDisplay *display,
@@ -1385,6 +1405,26 @@ gimp_tool_push_status_length (GimpTool            *tool,
   tool->status_displays = g_list_prepend (tool->status_displays, display);
 }
 
+/*
+ * gimp_tool_replace_status:
+ * @tool:
+ * @display:
+ * @format:
+ *
+ * Push a new status message for the context of the @tool, in the shell
+ * associated to @display. If any message for the same context (i.e.
+ * same tool) is already lined up, it will be replaced without changing
+ * the appearance order. In other words, it doesn't try to prioritize
+ * this new status message. Yet if no message for the same context
+ * existed already, the new status would end up front (except for any
+ * progress or temporary messages which might be going on and are always
+ * front).
+ * See also gimp_tool_push_status().
+ *
+ * Therefore you should not call gimp_tool_pop_status() first before
+ * calling gimp_tool_replace_status() as it would not be the same
+ * behavior and could trigger unnecessary redraws of the status bar.
+ */
 void
 gimp_tool_replace_status (GimpTool    *tool,
                           GimpDisplay *display,