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

@@ -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,