From f0c98db478b78b1d20290f6a1e9d310c052e98b4 Mon Sep 17 00:00:00 2001
From: Miguel de Icaza <miguel@gnome.org>
Date: Mon, 28 Jun 2004 17:33:17 +0000
Subject: [PATCH] A few contributions from me

svn path=/trunk/gtk-sharp/; revision=30481
---
 doc/en/Gtk/Requisition.xml | 17 +++++++++++------
 doc/en/Gtk/Widget.xml      |  9 ++++++++-
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/doc/en/Gtk/Requisition.xml b/doc/en/Gtk/Requisition.xml
index c3665dc18..9290be41d 100644
--- a/doc/en/Gtk/Requisition.xml
+++ b/doc/en/Gtk/Requisition.xml
@@ -10,8 +10,13 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
-    <remarks>To be added</remarks>
+    <summary>A GtkRequisition represents the desired size of a widget. </summary>
+    <remarks>The size requisition of a widget is it's desired width and height. This is represented by this structure.
+<para>
+How a widget determines its desired size depends on the widget. A <see cref="T:Gtk.Label" />, for example, requests enough space to display all its text. Container widgets generally base their size request on the requisitions of their children.
+</para><para>
+The size requisition phase of the widget layout process operates top-down. It starts at a top-level widget, typically a <see cref="T:Gtk.Window" />. The top-level widget asks its child for its size requisition by calling <see cref="M:Gtk.Widget.SizeRequest" />. To determine its requisition, the child asks its own children for their requisitions and so on. Finally, the top-level widget will get a requisition back from its child. 
+</para></remarks>
   </Docs>
   <Base>
     <BaseTypeName>System.ValueType</BaseTypeName>
@@ -94,8 +99,8 @@
       <Parameters>
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
-        <remarks>To be added</remarks>
+        <summary>The requested width.</summary>
+        <remarks />
       </Docs>
     </Member>
     <Member MemberName="Height">
@@ -107,8 +112,8 @@
       <Parameters>
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
-        <remarks>To be added</remarks>
+        <summary>The requested height.</summary>
+        <remarks />
       </Docs>
     </Member>
   </Members>
diff --git a/doc/en/Gtk/Widget.xml b/doc/en/Gtk/Widget.xml
index 775c9943b..c77939f0e 100644
--- a/doc/en/Gtk/Widget.xml
+++ b/doc/en/Gtk/Widget.xml
@@ -3833,7 +3833,14 @@ handle focus grabs.</returns>
       <Parameters />
       <Docs>
         <summary>Gets or Sets the widget's allocation.</summary>
-        <returns>a <see cref="T:Gdk.Rectangle" /> representing the size of the widget's allocation.</returns>
+        <returns>a <see cref="T:Gdk.Rectangle" /> representing the size of the widget's allocation.
+<para>
+When the top-level widget has determined how much space its child would like to have, the second phase of the size negotiation, size allocation, begins. Depending on its configuration (see <see cref="P:Gtk.Window.Resizable" />), the top-level widget may be able to expand in order to satisfy the size request or it may have to ignore the size request and keep its fixed size. It then tells its child widget how much space it gets by calling <see cref="M:Gtk.Widget.SizeAllocate(Gdk.Rectangle)" />. The child widget divides the space among its children and tells each child how much space it got, and so on. Under normal circumstances, a <see cref="T:Gtk.Window" /> will always give its child the amount of space the child requested.
+</para><para>
+A child's size allocation is represented by a <see cref="T:Gtk.Allocation" />. This struct contains not only a width and height, but also a position (i.e. X and Y coordinates), so that containers can tell their children not only how much space they have gotten, but also where they are positioned inside the space available to the container.
+</para><para>
+Widgets are required to honor the size allocation they receive; a size request is only a request, and widgets must be able to cope with any size. 
+</para></returns>
         <remarks>None.</remarks>
       </Docs>
     </Member>