From 890cd45ce49708750555c36979d909901c4bcab7 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Sat, 10 Mar 2018 21:29:46 -0500
Subject: [PATCH] Document new snapshot api

---
 docs/reference/gtk/gtk4-sections.txt |  5 +++
 docs/reference/gtk/gtk4.types.in     |  1 +
 gtk/gtksnapshot.c                    | 53 ++++++++++++++++++++++++++--
 3 files changed, 57 insertions(+), 2 deletions(-)

diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 742147f7c0..fb8707a246 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -4166,6 +4166,11 @@ gtk_volume_button_get_type
 <FILE>gtksnapshot</FILE>
 <TITLE>GtkSnapshot</TITLE>
 GtkSnapshot
+gtk_snapshot_new
+gtk_snapshot_ref
+gtk_snapshot_unref
+gtk_snapshot_to_node
+gtk_snapshot_free_to_node
 gtk_snapshot_push
 gtk_snapshot_push_transform
 gtk_snapshot_push_opacity
diff --git a/docs/reference/gtk/gtk4.types.in b/docs/reference/gtk/gtk4.types.in
index d416be89f6..1723d1f18c 100644
--- a/docs/reference/gtk/gtk4.types.in
+++ b/docs/reference/gtk/gtk4.types.in
@@ -146,6 +146,7 @@ gtk_shortcuts_section_get_type
 gtk_shortcuts_group_get_type
 gtk_shortcuts_shortcut_get_type
 gtk_size_group_get_type
+gtk_snapshot_get_type
 gtk_spin_button_get_type
 gtk_spinner_get_type
 gtk_stack_get_type
diff --git a/gtk/gtksnapshot.c b/gtk/gtksnapshot.c
index 88997155a8..ffc7217544 100644
--- a/gtk/gtksnapshot.c
+++ b/gtk/gtksnapshot.c
@@ -46,12 +46,21 @@
  * operates on. Use the gtk_snapshot_push() and gtk_snapshot_pop() functions to
  * change the current node.
  *
- * The only way to obtain a #GtkSnapshot object is as an argument to
- * the #GtkWidget::snapshot vfunc.
+ * The typical way to obtain a #GtkSnapshot object is as an argument to
+ * the #GtkWidget::snapshot vfunc. If you need to create your own GtkSnapshot,
+ * use gtk_snapshot_new().
  */
 
 G_DEFINE_BOXED_TYPE (GtkSnapshot, gtk_snapshot, gtk_snapshot_ref, gtk_snapshot_unref)
 
+/**
+ * gtk_snapshot_ref:
+ * @snapshot: a #GtkSnapshot
+ *
+ * Increase the reference count of @snapshot by 1.
+ *
+ * Returns: the @snapshot
+ */
 GtkSnapshot *
 gtk_snapshot_ref (GtkSnapshot *snapshot)
 {
@@ -62,6 +71,13 @@ gtk_snapshot_ref (GtkSnapshot *snapshot)
   return snapshot;
 }
 
+/**
+ * gtk_snapshot_unref:
+ * @snapshot: a #GtkSnapshot
+ *
+ * Decrease the reference count of @snapshot by 1 and
+ * free the object if the count drops to 0.
+ */
 void
 gtk_snapshot_unref (GtkSnapshot *snapshot)
 {
@@ -156,6 +172,18 @@ gtk_snapshot_state_clear (GtkSnapshotState *state)
   g_clear_pointer (&state->name, g_free);
 }
 
+/**
+ * gtk_snapshot_new:
+ * @renderer: the #GskRenderer to create nodes for
+ * @record_names: whether to keep node names (for debugging purposes)
+ * @clip: the clip region to use, or %NULL
+ * @name: a printf-style format string to create the node name
+ * @...: arguments for @name
+ *
+ * Creates a new #GtkSnapshot.
+ *
+ * Returns: a newly-allocated #GtkSnapshot
+ */
 GtkSnapshot *
 gtk_snapshot_new (GskRenderer          *renderer,
 							    gboolean              record_names,
@@ -195,6 +223,15 @@ gtk_snapshot_new (GskRenderer          *renderer,
   return snapshot;
 }
 
+/**
+ * gtk_snapshot_free_to_node:
+ * @snapshot: a #GtkSnapshot
+ *
+ * Returns the node that was constructed by @snapshot
+ * and frees @snapshot.
+ *
+ * Returns: a newly-created #GskRenderNode
+ */
 GskRenderNode *
 gtk_snapshot_free_to_node (GtkSnapshot *snapshot)
 {
@@ -1114,6 +1151,18 @@ gtk_snapshot_pop_internal (GtkSnapshot *snapshot)
   return node;
 }
 
+/**
+ * gtk_snapshot_to_node:
+ * @snapshot: a #GtkSnapshot
+ *
+ * Returns the render node that was constructed
+ * by @snapshot. 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 gtk_snapshot_unref().
+ *
+ * Returns: the constructed #GskRenderNode
+ */
 GskRenderNode *
 gtk_snapshot_to_node (GtkSnapshot *snapshot)
 {