[gtk/matthiasc/for-master] Document some API as widget-implementation only

[Matthias Clasen <matthiasc src gnome org>]

commit 67c1600ac257cdac6430434852c42b671ead6ca2
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Sep 14 20:28:44 2020 -0400

    Document some API as widget-implementation only
    
    Using gtk_widget_insert_before on a complex container
    is a *bad* idea; it will mess up the containers bookkeeping
    of its children and can easily lead to failure and crashes.

 gtk/gtkwidget.c | 36 ++++++++++++++++++++++++++++--------
 1 file changed, 28 insertions(+), 8 deletions(-)
---
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 2775d66388..df99bc01d2 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -11156,6 +11156,8 @@ gtk_widget_observe_controllers (GtkWidget *widget)
  *
  * Returns the widgets first child.
  *
+ * This API is primarily meant for widget implementations.
+ *
  * Returns: (transfer none) (nullable): The widget's first child
  */
 GtkWidget *
@@ -11174,6 +11176,8 @@ gtk_widget_get_first_child (GtkWidget *widget)
  *
  * Returns the widgets last child.
  *
+ * This API is primarily meant for widget implementations.
+ *
  * Returns: (transfer none) (nullable): The widget's last child
  */
 GtkWidget *
@@ -11192,6 +11196,8 @@ gtk_widget_get_last_child (GtkWidget *widget)
  *
  * Returns the widgets next sibling.
  *
+ * This API is primarily meant for widget implementations.
+ *
  * Returns: (transfer none) (nullable): The widget's next sibling
  */
 GtkWidget *
@@ -11210,6 +11216,8 @@ gtk_widget_get_next_sibling (GtkWidget *widget)
  *
  * Returns the widgets previous sibling.
  *
+ * This API is primarily meant for widget implementations.
+ *
  * Returns: (transfer none) (nullable): The widget's previous sibling
  */
 GtkWidget *
@@ -11229,12 +11237,18 @@ gtk_widget_get_prev_sibling (GtkWidget *widget)
  * @previous_sibling: (nullable): the new previous sibling of @widget or %NULL
  *
  * Inserts @widget into the child widget list of @parent.
- * It will be placed after @previous_sibling, or at the beginning if @previous_sibling is %NULL.
  *
- * After calling this function, gtk_widget_get_prev_sibling(widget) will return @previous_sibling.
+ * It will be placed after @previous_sibling, or at the beginning if
+ * @previous_sibling is %NULL.
  *
- * If @parent is already set as the parent widget of @widget, this function can also be used
- * to reorder @widget in the child widget list of @parent.
+ * After calling this function, gtk_widget_get_prev_sibling(widget) will
+ * return @previous_sibling.
+ *
+ * If @parent is already set as the parent widget of @widget, this function
+ * can also be used to reorder @widget in the child widget list of @parent.
+ *
+ * This API is primarily meant for widget implementations; if you are
+ * just using a widget, you *must* use its own API for adding children.
  */
 void
 gtk_widget_insert_after (GtkWidget *widget,
@@ -11265,12 +11279,18 @@ gtk_widget_insert_after (GtkWidget *widget,
  * @next_sibling: (nullable): the new next sibling of @widget or %NULL
  *
  * Inserts @widget into the child widget list of @parent.
- * It will be placed before @next_sibling, or at the end if @next_sibling is %NULL.
  *
- * After calling this function, gtk_widget_get_next_sibling(widget) will return @next_sibling.
+ * It will be placed before @next_sibling, or at the end if
+ * @next_sibling is %NULL.
+ *
+ * After calling this function, gtk_widget_get_next_sibling(widget)
+ * will return @next_sibling.
+ *
+ * If @parent is already set as the parent widget of @widget, this function
+ * can also be used to reorder @widget in the child widget list of @parent.
  *
- * If @parent is already set as the parent widget of @widget, this function can also be used
- * to reorder @widget in the child widget list of @parent.
+ * This API is primarily meant for widget implementations; if you are
+ * just using a widget, you *must* use its own API for adding children.
  */
 void
 gtk_widget_insert_before (GtkWidget *widget,