[gtk/present-toplevel-2: 177/178] toplevellayout: Add docs

[Matthias Clasen <matthiasc src gnome org>]

commit 24b134be568a83f61da28566460b3177a1976ea6
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Mar 9 13:36:47 2020 -0700

    toplevellayout: Add docs

 gdk/gdktoplevellayout.c | 117 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 113 insertions(+), 4 deletions(-)
---
diff --git a/gdk/gdktoplevellayout.c b/gdk/gdktoplevellayout.c
index b36a98e8bc..adbcf6d24d 100644
--- a/gdk/gdktoplevellayout.c
+++ b/gdk/gdktoplevellayout.c
@@ -22,6 +22,18 @@
 
 #include "gdkmonitor.h"
 
+/**
+ * SECTION:gdktoplevellayout
+ * @Title: GdkToplevelLayout
+ * @Short_description: Information for presenting toplevels
+ *
+ * Toplevel surfaces are sovereign windows that can be presented
+ * to the user in various states (maximized, on all workspaces,
+ * etc).
+ *
+ * The GdkToplevelLayout struct contains information that
+ * is necessary to do so, and is passed to gdk_toplevel_present().
+ */
 struct _GdkToplevelLayout
 {
   /* < private >*/
@@ -42,10 +54,13 @@ G_DEFINE_BOXED_TYPE (GdkToplevelLayout, gdk_toplevel_layout,
 
 /**
  * gdk_toplevel_layout_new: (constructor)
+ * @min_width: the minimum width for the layout
+ * @min_height: the minimum height for the layout
  *
- * Create a toplevel layout description. Used together with
- * gdk_surface_present_toplevel() to describe how a toplevel surface
- * should be placed and behave on-screen.
+ * Create a toplevel layout description.
+ *
+ * Used together with gdk_toplevel_present() to describe
+ * how a toplevel surface should be placed and behave on-screen.
  *
  * Returns: (transfer full): newly created instance of #GdkToplevelLayout
  */
@@ -153,18 +168,42 @@ gdk_toplevel_layout_equal (GdkToplevelLayout *layout,
          layout->fullscreen_monitor == other->fullscreen_monitor;
 }
 
+/**
+ * gdk_toplevel_layout_get_min_width:
+ * @layout: a #GdkToplevelLayout
+ *
+ * Returns the minimum width of the given layout.
+ *
+ * Returns: the minimum width of @layout
+ */
 int
 gdk_toplevel_layout_get_min_width (GdkToplevelLayout *layout)
 {
   return layout->min_width;
 }
 
+/**
+ * gdk_toplevel_layout_get_min_height:
+ * @layout: a #GdkToplevelLayout
+ *
+ * Returns the minimum height of the given layout.
+ *
+ * Returns: the minimum height of @layout
+ */
 int
 gdk_toplevel_layout_get_min_height (GdkToplevelLayout *layout)
 {
   return layout->min_height;
 }
 
+/**
+ * gdk_toplevel_layout_set_resizable:
+ * @layout: a #GdkToplevelLayout
+ * @resizable: %TRUE to allow resizing
+ *
+ * Sets whether the layout should allow the user
+ * to resize the surface after it has been presented.
+ */
 void
 gdk_toplevel_layout_set_resizable (GdkToplevelLayout *layout,
                                    gboolean           resizable)
@@ -172,12 +211,29 @@ gdk_toplevel_layout_set_resizable (GdkToplevelLayout *layout,
   layout->resizable = resizable;
 }
 
+/**
+ * gdk_toplevel_layout_get_resizable:
+ * @layout: a #GdkToplevelLayout
+ *
+ * Returns whether the layout should allow the user
+ * to resize the surface.
+ *
+ * Returns: %TRUE if the layout is resizable
+ */
 gboolean
 gdk_toplevel_layout_get_resizable (GdkToplevelLayout *layout)
 {
   return layout->resizable;
 }
 
+/**
+ * gdk_toplevel_layout_set_maximized:
+ * @layout: a #GdkToplevelLayout
+ * @maximized: %TRUE to maximize
+ *
+ * Sets whether the layout should cause the surface
+ * to be maximized when presented.
+ */
 void
 gdk_toplevel_layout_set_maximized (GdkToplevelLayout *layout,
                                    gboolean           maximized)
@@ -185,12 +241,30 @@ gdk_toplevel_layout_set_maximized (GdkToplevelLayout *layout,
   layout->maximized = maximized;
 }
 
+/**
+ * gdk_toplevel_layout_get_maximized:
+ * @layout: a #GdkToplevelLayout
+ *
+ * Returns whether the layout should present the
+ * surface as maximized.
+ *
+ * Returns: %TRUE if the layout is maximized
+ */
 gboolean
 gdk_toplevel_layout_get_maximized (GdkToplevelLayout *layout)
 {
   return layout->maximized;
 }
 
+/**
+ * gdk_toplevel_layout_set_fullscreen:
+ * @layout: a #GdkToplevelLayout
+ * @fullscreen: %TRUE to fullscreen the surface
+ * @monitor: (nullable): the monitor to fullscreen on
+ *
+ * Sets whether the layout should cause the surface
+ * to be fullscreen when presented.
+ */
 void
 gdk_toplevel_layout_set_fullscreen (GdkToplevelLayout *layout,
                                     gboolean           fullscreen,
@@ -201,18 +275,45 @@ gdk_toplevel_layout_set_fullscreen (GdkToplevelLayout *layout,
     layout->fullscreen_monitor = g_object_ref (monitor);
 }
 
+/**
+ * gdk_toplevel_layout_get_fullscreen:
+ * @layout: a #GdkToplevelLayout
+ *
+ * Returns whether the layout should cause the surface
+ * to be fullscreen when presented.
+ *
+ * Returns: %TRUE if @layout is fullscreen
+ */
 gboolean
 gdk_toplevel_layout_get_fullscreen (GdkToplevelLayout *layout)
 {
   return layout->fullscreen;
 }
 
+/**
+ * gdk_toplevel_layout_get_fullscreen_monitor:
+ * @layout: a #GdkToplevelLayout
+ *
+ * Returns the monitor that the layout is fullscreening
+ * the surface on.
+ *
+ * Returns: (nullable): the monitor on which @layout fullscreens
+ */
 GdkMonitor *
 gdk_toplevel_layout_get_fullscreen_monitor (GdkToplevelLayout *layout)
 {
   return layout->fullscreen_monitor;
 }
 
+/**
+ * gdk_toplevel_layout_set_modal:
+ * @layout: a #GdkToplevelLayout
+ * @modal: %TRUE to make the surface modal
+ *
+ * Sets whether the layout should cause the surface
+ * to block input on its transient-for parent surface
+ * while it is presented.
+ */
 void
 gdk_toplevel_layout_set_modal (GdkToplevelLayout *layout,
                                gboolean           modal)
@@ -220,7 +321,15 @@ gdk_toplevel_layout_set_modal (GdkToplevelLayout *layout,
   layout->modal = modal;
 }
 
-
+/**
+ * gdk_toplevel_layout_get_modal:
+ * @layout: a #GdkToplevelLayout
+ *
+ * Returns whether the layout should present the
+ * surface as modal.
+ *
+ * Returns: %TRUE if the layout is modal
+ */
 gboolean
 gdk_toplevel_layout_get_modal (GdkToplevelLayout *layout)
 {