gtk: Improve documentation on returned nodes for snapshot

Closes: #5747

diff --git a/gtk/gskpango.c b/gtk/gskpango.c
index 41a4b1a7bc8a8f501fc14b70e1d146ba03ef4a2a..c83f97f537f77f4d7aa1a854d71f30ceb0b87dc3 100644 (file)
--- a/gtk/gskpango.c
+++ b/gtk/gskpango.c
@@ -460,6 +460,9 @@ gsk_pango_renderer_release (GskPangoRenderer *renderer)
  * Creates render nodes for rendering @layout in the given foregound @color
  * and appends them to the current node of @snapshot without changing the
  * current node.
+ *
+ * Note that if the layout does not produce any visible output, then nodes
+ * may not be added to the @snapshot.
  **/
 void
 gtk_snapshot_append_layout (GtkSnapshot   *snapshot,

diff --git a/gtk/gtksnapshot.c b/gtk/gtksnapshot.c
index 76005769d83706e46a6ef30a4a164b282a0a9def..44123e9bae8e3ddb43c82c76793a2067f8642e88 100644 (file)
--- a/gtk/gtksnapshot.c
+++ b/gtk/gtksnapshot.c
@@ -300,6 +300,8 @@ gtk_snapshot_new (void)
  * Returns the node that was constructed by @snapshot
  * and frees @snapshot.
  *
+ * See also [method@Gtk.Snapshot.to_node].
+ *
  * Returns: (transfer full) (nullable): a newly-created [class@Gsk.RenderNode]
  */
 GskRenderNode *
@@ -1569,11 +1571,16 @@ gtk_snapshot_pop_collect (GtkSnapshot *snapshot)
  * Returns the render node that was constructed
  * by @snapshot.
  *
+ * Note that this function may return %NULL if nothing has been
+ * added to the snapshot or if its content does not produce pixels
+ * to be rendered.
+ *
  * After calling this function, it is no longer possible to
  * add more nodes to @snapshot. The only function that should
  * be called after this is [method@GObject.Object.unref].
  *
- * Returns: (transfer full) (nullable): the constructed `GskRenderNode`
+ * Returns: (transfer full) (nullable): the constructed `GskRenderNode` or
+ *   %NULL if there are no nodes to render.
  */
 GskRenderNode *
 gtk_snapshot_to_node (GtkSnapshot *snapshot)