From ca2a7c1efdba7d68aafe3baf281620abbced80a3 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Tue, 26 Dec 2017 14:39:24 -0500
Subject: [PATCH] Document more structs

---
 gdk/gdkclipboard.c       |  7 +++++++
 gdk/gdkcontentprovider.h |  6 ++++++
 gdk/gdkdevice.c          |  7 +++++++
 gdk/gdkdevicepad.c       |  7 +++++++
 gdk/gdkdisplay.c         |  6 ++++++
 gdk/gdkdisplaymanager.c  |  6 ++++++
 gdk/gdkdnd.c             |  7 +++++++
 gdk/gdkdrawcontext.c     | 12 +++++++++++-
 gdk/gdkdrawingcontext.c  |  7 +++++++
 gdk/gdkevents.c          | 13 +++++++++++++
 gdk/gdkframeclock.c      |  7 +++++++
 gdk/gdkframetimings.c    |  7 +++++++
 gdk/gdkglcontext.c       |  7 +++++++
 gdk/gdkseat.c            |  7 +++++++
 gdk/gdkwindow.c          |  6 ++++++
 15 files changed, 111 insertions(+), 1 deletion(-)

diff --git a/gdk/gdkclipboard.c b/gdk/gdkclipboard.c
index 63bd629ca0..b2d56418a2 100644
--- a/gdk/gdkclipboard.c
+++ b/gdk/gdkclipboard.c
@@ -55,6 +55,13 @@
  * which provides a #GInputStream object.
  */
 
+/**
+ * GdkClipboard:
+ *
+ * The GdkClipboard struct contains only private fields and should not be
+ * accessed directly.
+ */
+
 typedef struct _GdkClipboardPrivate GdkClipboardPrivate;
 
 struct _GdkClipboardPrivate
diff --git a/gdk/gdkcontentprovider.h b/gdk/gdkcontentprovider.h
index b33f266bfd..7af585f1a5 100644
--- a/gdk/gdkcontentprovider.h
+++ b/gdk/gdkcontentprovider.h
@@ -38,6 +38,12 @@ G_BEGIN_DECLS
 
 typedef struct _GdkContentProviderClass GdkContentProviderClass;
 
+/**
+ * GdkContentProvider:
+ *
+ * Should not be directly accessed.
+ */
+
 struct _GdkContentProvider
 {
   GObject parent;
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index afb639ce57..fb5cf9a6bf 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -42,6 +42,13 @@
  * relationships.
  */
 
+/**
+ * GdkDevice:
+ *
+ * The GdkDevice struct contains only private fields and
+ * should not be accessed directly.
+ */
+
 typedef struct _GdkAxisInfo GdkAxisInfo;
 
 struct _GdkAxisInfo
diff --git a/gdk/gdkdevicepad.c b/gdk/gdkdevicepad.c
index 02282f1068..cfb4780209 100644
--- a/gdk/gdkdevicepad.c
+++ b/gdk/gdkdevicepad.c
@@ -42,6 +42,13 @@
  *
  */
 
+/**
+ * GdkDevicePad:
+ *
+ * The GdkDevicePad struct contains only private fields and
+ * should not be accessed directly.
+ */
+
 #include "config.h"
 
 #include "gdkdevicepad.h"
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index f7085d54fd..cca05e8518 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -63,6 +63,12 @@
  * with gdk-display_get_monitor() and similar APIs.
  */
 
+/**
+ * GdkDisplay:
+ *
+ * The GdkDisplay struct contains only private field and should not
+ * be accessed directly.
+ */
 enum
 {
   PROP_0,
diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c
index 6af57cb704..40289b97cd 100644
--- a/gdk/gdkdisplaymanager.c
+++ b/gdk/gdkdisplaymanager.c
@@ -109,6 +109,12 @@
  * ]|
  */
 
+/**
+ * GdkDisplayManager:
+ *
+ * The GdkDisplayManager struct contains only private fields and
+ * should not be accessed directly.
+ */
 
 enum {
   PROP_0,
diff --git a/gdk/gdkdnd.c b/gdk/gdkdnd.c
index 44de31c25a..c8d0ba5931 100644
--- a/gdk/gdkdnd.c
+++ b/gdk/gdkdnd.c
@@ -84,6 +84,13 @@ static GList *contexts = NULL;
  * the GTK+ documentation for more information.
  */
 
+/**
+ * GdkDragContext:
+ *
+ * The GdkDragContext struct contains only private fields and
+ * should not be accessed directly.
+ */
+
 /**
  * gdk_drag_context_get_display:
  * @context: a #GdkDragContext
diff --git a/gdk/gdkdrawcontext.c b/gdk/gdkdrawcontext.c
index 56629e06d2..401cd65844 100644
--- a/gdk/gdkdrawcontext.c
+++ b/gdk/gdkdrawcontext.c
@@ -34,8 +34,18 @@
  * rendering methods, such as #GdkGLContext or #GdkVulkanContext. It provides
  * shared functionality between those contexts.
  *
- * You will always interact with one of those subclasses.
+ * You will always interact with one of those s.ubclasses.
+ *
+ * A GdkDrawContext is always associated with a single toplevel window.
  */
+
+/**
+ * GdkDrawContext:
+ *
+ * The GdkDrawContext struct contains only private fields and should not
+ * be accessed directly.
+ */
+
 typedef struct _GdkDrawContextPrivate GdkDrawContextPrivate;
 
 struct _GdkDrawContextPrivate {
diff --git a/gdk/gdkdrawingcontext.c b/gdk/gdkdrawingcontext.c
index 3776369fc2..31ab477706 100644
--- a/gdk/gdkdrawingcontext.c
+++ b/gdk/gdkdrawingcontext.c
@@ -32,6 +32,13 @@
  * #GdkDrawingContext is available since GDK 3.22
  */
 
+/**
+ * GdkDrawingContext:
+ *
+ * The GdkDrawingContext struct contains only private fields and should not
+ * be accessed directly.
+ */
+
 #include "config.h"
 
 #include <cairo-gobject.h>
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index 52adc9516b..e01479e71b 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -49,6 +49,19 @@
  * so these functions are rarely needed.
  */
 
+/**
+ * GdkEvent:
+ *
+ * The GdkEvent struct contains only private fields and
+ * should not be accessed directly.
+ */
+
+/**
+ * GdkEventSequence:
+ *
+ * GdkEventSequence is an opaque type representing a sequence
+ * of related touch events.
+ */
 
 typedef struct _GdkIOClosure GdkIOClosure;
 
diff --git a/gdk/gdkframeclock.c b/gdk/gdkframeclock.c
index f8450435ff..5e329304ab 100644
--- a/gdk/gdkframeclock.c
+++ b/gdk/gdkframeclock.c
@@ -67,6 +67,13 @@
  * they will stay exactly synchronized.
  */
 
+/**
+ * GdkFrameClock:
+ *
+ * The GdkFrameClock struct contains only private fields and
+ * should not be accessed directly.
+ */
+
 enum {
   FLUSH_EVENTS,
   BEFORE_PAINT,
diff --git a/gdk/gdkframetimings.c b/gdk/gdkframetimings.c
index 7b8a3dd88c..6fe08a3082 100644
--- a/gdk/gdkframetimings.c
+++ b/gdk/gdkframetimings.c
@@ -34,6 +34,13 @@
  * quality metrics for the application’s display, such as latency and jitter.
  */
 
+/**
+ * GdkFrameTimings:
+ *
+ * The GdkFrameTimings struct contains only private fields and
+ * should not be accessed directly.
+ */
+
 G_DEFINE_BOXED_TYPE (GdkFrameTimings, gdk_frame_timings,
                      gdk_frame_timings_ref,
                      gdk_frame_timings_unref)
diff --git a/gdk/gdkglcontext.c b/gdk/gdkglcontext.c
index 84bdd4038f..b0cbfdbdec 100644
--- a/gdk/gdkglcontext.c
+++ b/gdk/gdkglcontext.c
@@ -76,6 +76,13 @@
  * that is currently set by calling gdk_gl_context_clear_current().
  */
 
+/**
+ * GdkGLContext:
+ *
+ * The GdkGLContext struct contains only private fields and
+ * should not be accessed directly.
+ */
+
 #include "config.h"
 
 #include "gdkglcontextprivate.h"
diff --git a/gdk/gdkseat.c b/gdk/gdkseat.c
index c22400324a..c0b7290a16 100644
--- a/gdk/gdkseat.c
+++ b/gdk/gdkseat.c
@@ -36,6 +36,13 @@
  * that belong to a user.
  */
 
+/**
+ * GdkSeat:
+ *
+ * The GdkSeat struct contains only private fields and
+ * should not be accessed directly.
+ */
+
 typedef struct _GdkSeatPrivate GdkSeatPrivate;
 
 struct _GdkSeatPrivate
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 97fc36abde..9a10fceb18 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -68,6 +68,12 @@
  * each #GtkButton has a #GdkWindow associated with it.
  */
 
+/**
+ * GdkWindow:
+ *
+ * The GdkWindow struct contains only private fields and
+ * should not be accessed directly.
+ */
 
 /* Historically a GdkWindow always matches a platform native window,
  * be it a toplevel window or a child window. In this setup the