Merge branch 'matthiasc/for-master' into 'master'

Matthiasc/for master

See merge request GNOME/gtk!2760

20 files changed, 144 insertions, 104 deletions

diff --git a/docs/reference/gdk/gdk4-docs.xml b/docs/reference/gdk/gdk4-docs.xml
index 3e1ed5f974..50b018be9d 100644
--- a/docs/reference/gdk/gdk4-docs.xml
+++ b/docs/reference/gdk/gdk4-docs.xml
@@ -16,14 +16,16 @@
     </releaseinfo>
   </bookinfo>
 
-  <reference id="reference">
+  <chapter>
     <title>API Reference</title>
     <xi:include href="xml/general.xml" />
     <xi:include href="xml/gdkdisplaymanager.xml" />
     <xi:include href="xml/gdkdisplay.xml" />
     <xi:include href="xml/gdkseat.xml" />
     <xi:include href="xml/gdkdevice.xml" />
-    <xi:include href="xml/gdkdevicepad.xml" />
+    <section>
+      <xi:include href="xml/gdkdevicepad.xml" />
+    </section>
     <xi:include href="xml/gdkmonitor.xml" />
     <xi:include href="xml/regions.xml" />
     <xi:include href="xml/textures.xml" />
@@ -32,16 +34,24 @@
     <xi:include href="xml/cursors.xml" />
     <xi:include href="xml/gdksurface.xml" />
     <xi:include href="xml/gdktoplevel.xml" />
-    <xi:include href="xml/gdktoplevellayout.xml" />
-    <xi:include href="xml/gdktoplevelsize.xml" />
+    <section>
+      <xi:include href="xml/gdktoplevellayout.xml" />
+      <xi:include href="xml/gdktoplevelsize.xml" />
+    </section>
     <xi:include href="xml/gdkpopup.xml" />
-    <xi:include href="xml/gdkpopuplayout.xml" />
+    <section>
+      <xi:include href="xml/gdkpopuplayout.xml" />
+    </section>
     <xi:include href="xml/gdkframeclock.xml" />
-    <xi:include href="xml/gdkframetimings.xml" />
+    <section>
+      <xi:include href="xml/gdkframetimings.xml" />
+    </section>
     <xi:include href="xml/gdkdrawcontext.xml" />
-    <xi:include href="xml/gdkglcontext.xml" />
-    <xi:include href="xml/gdkvulkancontext.xml" />
-    <xi:include href="xml/gdkcairocontext.xml" />
+    <section>
+      <xi:include href="xml/gdkglcontext.xml" />
+      <xi:include href="xml/gdkvulkancontext.xml" />
+      <xi:include href="xml/gdkcairocontext.xml" />
+    </section>
     <xi:include href="xml/events.xml" />
     <xi:include href="xml/keys.xml" />
     <xi:include href="xml/gdkclipboard.xml" />
@@ -50,13 +60,16 @@
     <xi:include href="xml/gdkcontentprovider.xml" />
     <xi:include href="xml/gdkcontentserializer.xml" />
     <xi:include href="xml/gdkcontentdeserializer.xml" />
-    <xi:include href="xml/gdkapplaunchcontext.xml" />
     <xi:include href="xml/pixbufs.xml" />
     <xi:include href="xml/pango_interaction.xml" />
     <xi:include href="xml/cairo_interaction.xml" />
+  </chapter>
+  <chapter>
+    <title>GDK Platform Support</title>
+    <xi:include href="xml/gdkapplaunchcontext.xml" />
     <xi:include href="xml/x_interaction.xml" />
     <xi:include href="xml/wayland_interaction.xml" />
-  </reference>
+  </chapter>
 
   <index id="api-index-full">
     <title>Index of all symbols</title>
diff --git a/docs/reference/gdk/gdk4-overrides.txt b/docs/reference/gdk/gdk4-overrides.txt
index 4123476674..5dab67c7c9 100644
--- a/docs/reference/gdk/gdk4-overrides.txt
+++ b/docs/reference/gdk/gdk4-overrides.txt
@@ -10,8 +10,8 @@
 </MACRO>
 
 <MACRO>
-<NAME>GDK_WINDOWING_QUARTZ</NAME>
-#define GDK_WINDOWING_QUARTZ
+<NAME>GDK_WINDOWING_MACOS</NAME>
+#define GDK_WINDOWING_MACOS
 </MACRO>
 
 <MACRO>
diff --git a/docs/reference/gdk/gdk4-sections.txt b/docs/reference/gdk/gdk4-sections.txt
index 9373f948f3..efbc18fc5b 100644
--- a/docs/reference/gdk/gdk4-sections.txt
+++ b/docs/reference/gdk/gdk4-sections.txt
@@ -8,7 +8,7 @@
 <SUBSECTION>
 GDK_WINDOWING_X11
 GDK_WINDOWING_WIN32
-GDK_WINDOWING_QUARTZ
+GDK_WINDOWING_MACOS
 GDK_WINDOWING_WAYLAND
 
 <SUBSECTION>
@@ -303,11 +303,8 @@ gdk_cairo_draw_from_gl
 </SECTION>
 
 <SECTION>
-<TITLE>Points, Rectangles and Regions</TITLE>
+<TITLE>Rectangles and Regions</TITLE>
 <FILE>regions</FILE>
-GdkPoint
-
-<SUBSECTION>
 GdkRectangle
 gdk_rectangle_intersect
 gdk_rectangle_union
diff --git a/gdk/gdk.c b/gdk/gdk.c
index 1cb48f411b..874e993892 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -87,12 +87,12 @@
  */
 
 /**
- * GDK_WINDOWING_QUARTZ:
+ * GDK_WINDOWING_MACOS:
  *
- * The #GDK_WINDOWING_QUARTZ macro is defined if the Quartz backend
+ * The #GDK_WINDOWING_MACOS macro is defined if the MacOS backend
  * is supported.
  *
- * Use this macro to guard code that is specific to the Quartz backend.
+ * Use this macro to guard code that is specific to the MacOS backend.
  */
 
 /**
diff --git a/gdk/gdkcursor.c b/gdk/gdkcursor.c
index 354d3e2cd9..8fd33d1d7b 100644
--- a/gdk/gdkcursor.c
+++ b/gdk/gdkcursor.c
@@ -43,13 +43,13 @@
  *
  * These functions are used to create and destroy cursors. Cursors
  * are immutable objects, so once you created them, there is no way
- * to modify them later. Create a new cursor, when you want to change
+ * to modify them later. Create a new cursor when you want to change
  * something about it.
  *
  * Cursors by themselves are not very interesting, they must be
  * bound to a window for users to see them. This is done with
  * gdk_surface_set_cursor() or gdk_surface_set_device_cursor().
- * Applications will typically use higher-level GTK+ functions such
+ * Applications will typically use higher-level GTK functions such
  * as gtk_widget_set_cursor() instead.
  *
  * Cursors are not bound to a given #GdkDisplay, so they can be shared.
@@ -59,16 +59,19 @@
  * There are multiple ways to create cursors. The platform's own cursors
  * can be created with gdk_cursor_new_from_name(). That function lists
  * the commonly available names that are shared with the CSS specification.
- * Other names may be available, depending on the platform in use.
+ * Other names may be available, depending on the platform in use. On some
+ * platforms, what images are used for named cursors may be influenced by
+ * the cursor theme.
+ *
  * Another option to create a cursor is to use gdk_cursor_new_from_texture()
  * and provide an image to use for the cursor.
  *
  * To ease work with unsupported cursors, a fallback cursor can be provided.
  * If a #GdkSurface cannot use a cursor because of the reasons mentioned above,
- * it will try the fallback cursor. Of course, fallback cursors can themselves
- * have fallback cursors again, so it is possible to provide a chain of
- * progressively easier to support cursors. If none of the provided cursors
- * can be supported, the default cursor will be the ultimate fallback.
+ * it will try the fallback cursor. Fallback cursors can themselves have fallback
+ * cursors again, so it is possible to provide a chain of progressively easier
+ * to support cursors. If none of the provided cursors can be supported, the
+ * default cursor will be the ultimate fallback.
  */
 
 /**
@@ -175,40 +178,40 @@ gdk_cursor_class_init (GdkCursorClass *cursor_class)
   object_class->finalize = gdk_cursor_finalize;
 
   g_object_class_install_property (object_class,
-				   PROP_FALLBACK,
-				   g_param_spec_object ("fallback",
+                                   PROP_FALLBACK,
+                                   g_param_spec_object ("fallback",
                                                         P_("Fallback"),
                                                         P_("Cursor image to fall back to if this cursor cannot be displayed"),
                                                         GDK_TYPE_CURSOR,
                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                         G_PARAM_STATIC_STRINGS));
   g_object_class_install_property (object_class,
-				   PROP_HOTSPOT_X,
-				   g_param_spec_int ("hotspot-x",
+                                   PROP_HOTSPOT_X,
+                                   g_param_spec_int ("hotspot-x",
                                                      P_("Hotspot X"),
                                                      P_("Horizontal offset of the cursor hotspot"),
                                                      0, G_MAXINT, 0,
                                                      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                      G_PARAM_STATIC_STRINGS));
   g_object_class_install_property (object_class,
-				   PROP_HOTSPOT_Y,
-				   g_param_spec_int ("hotspot-y",
+                                   PROP_HOTSPOT_Y,
+                                   g_param_spec_int ("hotspot-y",
                                                      P_("Hotspot Y"),
                                                      P_("Vertical offset of the cursor hotspot"),
                                                      0, G_MAXINT, 0,
                                                      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                      G_PARAM_STATIC_STRINGS));
   g_object_class_install_property (object_class,
-				   PROP_NAME,
-				   g_param_spec_string ("name",
+                                   PROP_NAME,
+                                   g_param_spec_string ("name",
                                                         P_("Name"),
                                                         P_("Name of this cursor"),
                                                         NULL,
                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
                                                         G_PARAM_STATIC_STRINGS));
   g_object_class_install_property (object_class,
-				   PROP_TEXTURE,
-				   g_param_spec_object ("texture",
+                                   PROP_TEXTURE,
+                                   g_param_spec_object ("texture",
                                                         P_("Texture"),
                                                         P_("The texture displayed by this cursor"),
                                                         GDK_TYPE_TEXTURE,
@@ -345,8 +348,8 @@ gdk_cursor_new_from_name (const char *name,
  */
 GdkCursor *
 gdk_cursor_new_from_texture (GdkTexture *texture,
-			     int         hotspot_x,
-			     int         hotspot_y,
+                             int         hotspot_x,
+                             int         hotspot_y,
                              GdkCursor  *fallback)
 {
   g_return_val_if_fail (GDK_IS_TEXTURE (texture), NULL);
@@ -390,7 +393,7 @@ gdk_cursor_get_fallback (GdkCursor *cursor)
  * @cursor: a #GdkCursor.
  *
  * Returns the name of the cursor. If the cursor is not a named cursor, %NULL
- * will be returned and the GdkCursor::texture property will be set.
+ * will be returned.
  *
  * Returns: (transfer none) (nullable): the name of the cursor or %NULL if it is not
  *     a named cursor
@@ -408,7 +411,7 @@ gdk_cursor_get_name (GdkCursor *cursor)
  * @cursor: a #GdkCursor.
  *
  * Returns the texture for the cursor. If the cursor is a named cursor, %NULL
- * will be returned and the GdkCursor::name property will be set.
+ * will be returned.
  *
  * Returns: (transfer none) (nullable): the texture for cursor or %NULL if it is a
  *     named cursor
@@ -428,6 +431,10 @@ gdk_cursor_get_texture (GdkCursor *cursor)
  * Returns the horizontal offset of the hotspot. The hotspot indicates the
  * pixel that will be directly above the cursor.
  *
+ * Note that named cursors may have a nonzero hotspot, but this function
+ * will only return the hotspot position for cursors created with
+ * gdk_cursor_new_from_texture().
+ *
  * Returns: the horizontal offset of the hotspot or 0 for named cursors
  */
 int
@@ -445,6 +452,10 @@ gdk_cursor_get_hotspot_x (GdkCursor *cursor)
  * Returns the vertical offset of the hotspot. The hotspot indicates the
  * pixel that will be directly above the cursor.
  *
+ * Note that named cursors may have a nonzero hotspot, but this function
+ * will only return the hotspot position for cursors created with
+ * gdk_cursor_new_from_texture().
+ *
  * Returns: the vertical offset of the hotspot or 0 for named cursors
  */
 int
@@ -454,4 +465,3 @@ gdk_cursor_get_hotspot_y (GdkCursor *cursor)
 
   return cursor->hotspot_y;
 }
-
diff --git a/gdk/gdkcursor.h b/gdk/gdkcursor.h
index a2f161bd58..1a0ea5d772 100644
--- a/gdk/gdkcursor.h
+++ b/gdk/gdkcursor.h
@@ -46,15 +46,15 @@ GType      gdk_cursor_get_type           (void) G_GNUC_CONST;
 
 GDK_AVAILABLE_IN_ALL
 GdkCursor* gdk_cursor_new_from_texture   (GdkTexture      *texture,
-					  int              hotspot_x,
-					  int              hotspot_y,
+                                          int              hotspot_x,
+                                          int              hotspot_y,
                                           GdkCursor       *fallback);
 GDK_AVAILABLE_IN_ALL
-GdkCursor*  gdk_cursor_new_from_name	 (const char      *name,
+GdkCursor*  gdk_cursor_new_from_name     (const char      *name,
                                           GdkCursor       *fallback);
 
 GDK_AVAILABLE_IN_ALL
-GdkCursor * gdk_cursor_get_fallback      (GdkCursor	  *cursor);
+GdkCursor * gdk_cursor_get_fallback      (GdkCursor       *cursor);
 GDK_AVAILABLE_IN_ALL
 const char *gdk_cursor_get_name          (GdkCursor       *cursor);
 GDK_AVAILABLE_IN_ALL
diff --git a/gdk/gdkframeclock.c b/gdk/gdkframeclock.c
index 4d05da780c..5e4492744c 100644
--- a/gdk/gdkframeclock.c
+++ b/gdk/gdkframeclock.c
@@ -29,11 +29,11 @@
 
 /**
  * SECTION:gdkframeclock
- * @Short_description: Frame clock syncs painting to a window or display
- * @Title: Frame clock
+ * @Title: GdkFrameClock
+ * @Short_description: Synchronizes painting to a surface
  *
- * A #GdkFrameClock tells the application when to update and repaint a
- * window. This may be synced to the vertical refresh rate of the
+ * A #GdkFrameClock tells the application when to update and repaint
+ * a surface. This may be synced to the vertical refresh rate of the
  * monitor, for example. Even when the frame clock uses a simple timer
  * rather than a hardware-based vertical sync, the frame clock helps
  * because it ensures everything paints at the same time (reducing the
diff --git a/gdk/gdkpaintable.c b/gdk/gdkpaintable.c
index 6d1f176b4d..a1726401b0 100644
--- a/gdk/gdkpaintable.c
+++ b/gdk/gdkpaintable.c
@@ -35,7 +35,7 @@ void            gtk_snapshot_pop                        (GdkSnapshot
  * @Short_description: An interface for a paintable region
  * @See_also: #ClutterContent, #GtkImage, #GdkTexture, #GtkSnapshot
  *
- * #GdkPaintable is a simple interface used by GDK and GDK to represent
+ * #GdkPaintable is a simple interface used by GDK and GTK to represent
  * objects that can be painted anywhere at any size without requiring any
  * sort of layout. The interface is inspired by similar concepts elsewhere,
  * such as [ClutterContent](https://developer.gnome.org/clutter/stable/ClutterContent.html),
@@ -347,22 +347,22 @@ gdk_paintable_get_intrinsic_height (GdkPaintable *paintable)
  * @paintable: a #GdkPaintable
  *
  * Gets the preferred aspect ratio the @paintable would like to be displayed at.
- * The aspect ration is the width divided by the height, so a value of 0.5 means
+ * The aspect ratio is the width divided by the height, so a value of 0.5 means
  * that the @paintable prefers to be displayed twice as high as it is wide.
  * Consumers of this interface can use this to preserve aspect ratio when displaying
- * this paintable.
+ * the paintable.
  *
  * This is a purely informational value and does not in any way limit the values
  * that may be passed to gdk_paintable_snapshot().
  *
- * Usually when a @paintable returns non-0 values from
+ * Usually when a @paintable returns nonzero values from
  * gdk_paintable_get_intrinsic_width() and gdk_paintable_get_intrinsic_height()
  * the aspect ratio should conform to those values, though that is not required.
  *
- * If the @paintable does not have a preferred aspect ratio, it returns 0.0.
+ * If the @paintable does not have a preferred aspect ratio, it returns 0.
  * Negative values are never returned.
  *
- * Returns: the intrinsic aspect ratio of @paintable or 0.0 if none.
+ * Returns: the intrinsic aspect ratio of @paintable or 0 if none.
  */
 double
 gdk_paintable_get_intrinsic_aspect_ratio (GdkPaintable *paintable)
@@ -379,9 +379,9 @@ gdk_paintable_get_intrinsic_aspect_ratio (GdkPaintable *paintable)
  * gdk_paintable_invalidate_contents:
  * @paintable: a #GdkPaintable
  *
- * Called by implementations of #GdkPaintable to invalidate their contents.  
+ * Called by implementations of #GdkPaintable to invalidate their contents.
  * Unless the contents are invalidated, implementations must guarantee that
- * multiple calls to GdkPaintable::snapshot produce the same output.
+ * multiple calls of gdk_paintable_snapshot() produce the same output.
  *
  * This function will emit the #GdkPaintable::invalidate-contents signal.
  *
@@ -401,9 +401,9 @@ gdk_paintable_invalidate_contents (GdkPaintable *paintable)
  * gdk_paintable_invalidate_size:
  * @paintable: a #GdkPaintable
  *
- * Called by implementations of #GdkPaintable to invalidate their size.  
- * As long as the size is not invalidated, @paintable must return the same values
- * for its width, height and intrinsic height.
+ * Called by implementations of #GdkPaintable to invalidate their size.
+ * As long as the size is not invalidated, @paintable must return the same
+ * values for its intrinsic width, height and aspect ratio.
  *
  * This function will emit the #GdkPaintable::invalidate-size signal.
  *
@@ -435,7 +435,7 @@ gdk_paintable_invalidate_size (GdkPaintable *paintable)
  * @concrete_height: (out): will be set to the concrete height
  *     computed.
  *
- * Applies the sizing algorithm outlined in 
+ * Applies the sizing algorithm outlined in
  * https://drafts.csswg.org/css-images-3/#default-sizing
  * to the given @paintable. See that link for more details.
  *
diff --git a/gdk/gdkpopup.c b/gdk/gdkpopup.c
index 91772d3c18..375a0fcb92 100644
--- a/gdk/gdkpopup.c
+++ b/gdk/gdkpopup.c
@@ -27,9 +27,13 @@
  * SECTION:gdkpopup
  * @Short_description: Interface for popup surfaces
  * @Title: Popups
+ * @See_also: #GdkToplevel, #GdkSurface
  *
  * A #GdkPopup is a surface that is attached to another surface,
- * and is positioned relative to it.
+ * called its #GdkPopup:parent, and is positioned relative to it.
+ *
+ * #GdkPopups are typically used to implement menus and similar popups.
+ * They can be modal, which is indicated by the #GdkPopup:autohide property.
  */
 
 G_DEFINE_INTERFACE (GdkPopup, gdk_popup, GDK_TYPE_SURFACE)
diff --git a/gdk/gdkrectangle.c b/gdk/gdkrectangle.c
index edae510625..8043716044 100644
--- a/gdk/gdkrectangle.c
+++ b/gdk/gdkrectangle.c
@@ -30,21 +30,23 @@
 
 /**
  * SECTION:regions
- * @Short_description: Simple graphical data types
- * @Title: Points and Rectangles
+ * @Short_description: Simple graphical data type
+ * @Title: GdkRectangle
  *
- * GDK provides the #GdkPoint and #GdkRectangle data types for representing pixels
- * and sets of pixels on the screen. Together with Cairo’s #cairo_region_t data
- * type, they make up the central types for representing graphical data.
- *
- * A #GdkPoint represents an x and y coordinate of a point.
+ * GDK provides a #GdkRectangle data type for representing rectangles.
+ * Together with Cairo’s #cairo_region_t data type, these are the central
+ * types for representing sets of pixels.
  *
  * A #GdkRectangle represents the position and size of a rectangle.
  * The intersection of two rectangles can be computed with
  * gdk_rectangle_intersect(). To find the union of two rectangles use
  * gdk_rectangle_union().
  *
- * #cairo_region_t is usually used for managing clipping of graphical operations.
+ * #cairo_region_t is usually used for managing clipping of graphical
+ * operations.
+ *
+ * The graphene library has a number of other data types for regions and
+ * volumes in 2D and 3D.
  */
 
 
diff --git a/gdk/gdkrgba.c b/gdk/gdkrgba.c
index fac9d2efa5..1de2bd45a9 100644
--- a/gdk/gdkrgba.c
+++ b/gdk/gdkrgba.c
@@ -32,10 +32,10 @@
 
 /**
  * SECTION:rgba_colors
+ * @Title: GdkRGBA
  * @Short_description: RGBA colors
- * @Title: RGBA Colors
  *
- * #GdkRGBA is a convenient way to pass rgba colors around.
+ * #GdkRGBA is a convenient way to pass colors around.
  * It’s based on cairo’s way to deal with colors and mirrors its behavior.
  * All values are in the range from 0.0 to 1.0 inclusive. So the color
  * (0.0, 0.0, 0.0, 0.0) represents transparent black and
diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c
index c32c17262b..43d3371609 100644
--- a/gdk/gdksurface.c
+++ b/gdk/gdksurface.c
@@ -55,10 +55,17 @@
  * SECTION:gdksurface
  * @Short_description: Onscreen display areas in the target window system
  * @Title: Surfaces
+ * @See_also: #GdkToplevel, #GdkPopup
  *
  * A #GdkSurface is a (usually) rectangular region on the screen.
- * It’s a low-level object, used to implement high-level objects such as
- * #GtkWindow on the GTK level.
+ * It’s a low-level object, used to implement high-level objects
+ * such as #GtkWindow or #GtkDialog in GTK.
+ *
+ * The surfaces you see in practice are either #GdkToplevel or
+ * #GdkPopup, and those interfaces provide much of the required
+ * API to interact with these surfaces. Other, more specialized
+ * surface types exist, but you will rarely interact with them
+ * directly.
  */
 
 /**
diff --git a/gdk/gdktexture.c b/gdk/gdktexture.c
index c28bd9575f..d54bb73e16 100644
--- a/gdk/gdktexture.c
+++ b/gdk/gdktexture.c
@@ -202,7 +202,7 @@ gdk_texture_class_init (GdkTextureClass *klass)
   /**
    * GdkTexture:width:
    *
-   * The width of the texture.
+   * The width of the texture, in pixels.
    */
   properties[PROP_WIDTH] =
     g_param_spec_int ("width",
@@ -219,7 +219,7 @@ gdk_texture_class_init (GdkTextureClass *klass)
   /**
    * GdkTexture:height:
    *
-   * The height of the texture.
+   * The height of the texture, in pixels.
    */
   properties[PROP_HEIGHT] =
     g_param_spec_int ("height",
@@ -281,7 +281,7 @@ gdk_texture_new_for_surface (cairo_surface_t *surface)
  * gdk_texture_new_for_pixbuf:
  * @pixbuf: a #GdkPixbuf
  *
- * Creates a new texture object representing the GdkPixbuf.
+ * Creates a new texture object representing the #GdkPixbuf.
  *
  * Returns: a new #GdkTexture
  */
@@ -316,7 +316,9 @@ gdk_texture_new_for_pixbuf (GdkPixbuf *pixbuf)
  * @resource_path: the path of the resource file
  *
  * Creates a new texture by loading an image from a resource.
- * The file format is detected automatically.
+ * The file format is detected automatically, and can be any
+ * format that is supported by the gdk-pixbuf library, such as
+ * JPEG or PNG.
  *
  * It is a fatal error if @resource_path does not specify a valid
  * image resource and the program will abort if that happens.
@@ -349,8 +351,12 @@ gdk_texture_new_from_resource (const char *resource_path)
  * @file: #GFile to load
  * @error: Return location for an error
  *
- * Creates a new texture by loading an image from a file.  The file format is
- * detected automatically. If %NULL is returned, then @error will be set.
+ * Creates a new texture by loading an image from a file.
+ * The file format is detected automatically, and can be any
+ * format that is supported by the gdk-pixbuf library, such as
+ * JPEG or PNG.
+ *
+ * If %NULL is returned, then @error will be set.
  *
  * Return value: A newly-created #GdkTexture or %NULL if an error occurred.
  **/
@@ -384,7 +390,7 @@ gdk_texture_new_from_file (GFile   *file,
  * gdk_texture_get_width:
  * @texture: a #GdkTexture
  *
- * Returns the width of @texture.
+ * Returns the width of @texture, in pixels.
  *
  * Returns: the width of the #GdkTexture
  */
@@ -400,7 +406,7 @@ gdk_texture_get_width (GdkTexture *texture)
  * gdk_texture_get_height:
  * @texture: a #GdkTexture
  *
- * Returns the height of the @texture.
+ * Returns the height of the @texture, in pixels.
  *
  * Returns: the height of the #GdkTexture
  */
@@ -573,4 +579,3 @@ gdk_texture_save_to_png (GdkTexture *texture,
 
   return result;
 }
-
diff --git a/gdk/gdktoplevel.c b/gdk/gdktoplevel.c
index 38a527c1ba..34328db10d 100644
--- a/gdk/gdktoplevel.c
+++ b/gdk/gdktoplevel.c
@@ -30,8 +30,14 @@
  * SECTION:gdktoplevel
  * @Short_description: Interface for toplevel surfaces
  * @Title: Toplevels
+ * @See_also: #GdkSurface, #GdkPopup
  *
  * A #GdkToplevel is a freestanding toplevel surface.
+ *
+ * The #GdkToplevel interface provides useful APIs for
+ * interacting with the windowing system, such as controlling
+ * maximization and size of the surface, setting icons and
+ * transient parents for dialogs.
  */
 
 G_DEFINE_INTERFACE (GdkToplevel, gdk_toplevel, GDK_TYPE_SURFACE)
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index 0a0068e181..da12f125bc 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -54,20 +54,6 @@ G_BEGIN_DECLS
 #define GDK_CURRENT_TIME     0L
 
 /**
- * GdkPoint:
- * @x: the x coordinate of the point
- * @y: the y coordinate of the point
- *
- * Defines the x and y coordinates of a point.
- */
-struct _GdkPoint
-{
-  int x;
-  int y;
-};
-typedef struct _GdkPoint              GdkPoint;
-
-/**
  * GdkRectangle:
  * @x: the x coordinate of the top left corner
  * @y: the y coordinate of the top left corner
diff --git a/gdk/macos/GdkMacosWindow.c b/gdk/macos/GdkMacosWindow.c
index b511233cdf..92cfa622eb 100644
--- a/gdk/macos/GdkMacosWindow.c
+++ b/gdk/macos/GdkMacosWindow.c
@@ -33,6 +33,7 @@
 #include "gdkmacossurface-private.h"
 #include "gdkmacospopupsurface-private.h"
 #include "gdkmacostoplevelsurface-private.h"
+#include "gdkmacosutils-private.h"
 
 #include "gdkmonitorprivate.h"
 #include "gdksurfaceprivate.h"
diff --git a/gdk/macos/edgesnapping.h b/gdk/macos/edgesnapping.h
index 8769ea7e47..b7ffd8a176 100644
--- a/gdk/macos/edgesnapping.h
+++ b/gdk/macos/edgesnapping.h
@@ -22,6 +22,7 @@
 #define __EDGE_SNAPPING_H__
 
 #include "gdktypes.h"
+#include "gdkmacosutils-private.h"
 
 G_BEGIN_DECLS
 
diff --git a/gdk/macos/gdkmacosutils-private.h b/gdk/macos/gdkmacosutils-private.h
index 678982ba97..6b81fd28ac 100644
--- a/gdk/macos/gdkmacosutils-private.h
+++ b/gdk/macos/gdkmacosutils-private.h
@@ -33,4 +33,12 @@ queue_contains (GQueue *queue,
   return queue->head == link_ || link_->prev || link_->next;
 }
 
+struct _GdkPoint
+{
+  int x;
+  int y;
+};
+typedef struct _GdkPoint GdkPoint;
+
+
 #endif /* __GDK_MACOS_UTILS_PRIVATE_H__ */
diff --git a/gdk/x11/gdkmain-x11.c b/gdk/x11/gdkmain-x11.c
index b7a7e3b9cd..7c5fbf2763 100644
--- a/gdk/x11/gdkmain-x11.c
+++ b/gdk/x11/gdkmain-x11.c
@@ -68,10 +68,10 @@
  *     }
  *   else
  * #endif
- * #ifdef GDK_WINDOWING_QUARTZ
- *   if (GDK_IS_QUARTZ_DISPLAY (display))
+ * #ifdef GDK_WINDOWING_MACOS
+ *   if (GDK_IS_MACOS_DISPLAY (display))
  *     {
- *       // make Quartz-specific calls here
+ *       // make MacOS-specific calls here
  *     }
  *   else
  * #endif
diff --git a/testsuite/gtk/autotestkeywords.cc b/testsuite/gtk/autotestkeywords.cc
index 04c637ea1e..971fdc50ac 100644
--- a/testsuite/gtk/autotestkeywords.cc
+++ b/testsuite/gtk/autotestkeywords.cc
@@ -4,9 +4,9 @@
 #include <gdk/broadway/gdkbroadway.h>
 #endif
 
-#ifdef GDK_WINDOWING_QUARTZ
+#ifdef GDK_WINDOWING_MACOS
 #if HAVE_OBJC
-#include <gdk/quartz/gdkquartz.h>
+#include <gdk/macos/gdkmacos.h>
 #endif
 #endif