Gorgeous and wonderul docs from maarten@alpha-cursus.nl

svn path=/trunk/gtk-sharp/; revision=88753

doc/en/Gdk/GC.xml

@@ -182,7 +182,7 @@
       </Parameters>
       <Docs>
         <summary>Retrieves the current values from a graphics context.</summary>
-        <param name="values">the GdkGCValues structure in which to store the results.</param>
+        <param name="values">the <see cref="T:Gdk.GCValues" /> structure in which to store the results.</param>
         <remarks>
           <para>Retrieves the current values from a graphics context.</para>
         </remarks>

doc/en/Gtk/ComboBox.xml

@@ -648,9 +648,9 @@ Default value: 0
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
+        <summary>Sets or gets whether the combo box will grab focus when it is clicked with the mouse.</summary>
         <value>a <see cref="T:System.Boolean" /></value>
-        <remarks>To be added</remarks>
+        <remarks>Making mouse clicks not grab focus is useful in places like toolbars where you don't want the keyboard focus removed from the main area of the application.</remarks>
         <since version="Gtk# 2.6" />
       </Docs>
       <Attributes>

doc/en/Gtk/FileChooser.xml

@@ -8,7 +8,7 @@
   <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>Interface for a file-chooser.</summary>
-    <remarks>See <see cref="M:Gtk.FileChooserWidget" /> for an actual implementation.</remarks>
+    <remarks>See <see cref="T:Gtk.FileChooserWidget" /> for an actual implementation.</remarks>
     <since version="Gtk# 2.4" />
   </Docs>
   <Interfaces>

doc/en/Gtk/FileChooserAction.xml

@@ -7,7 +7,7 @@
   </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>Describes whether a <see cref="T:FileChooser" /> is being used to open existing files or to save to a possibly new file.</summary>
+    <summary>Describes whether a <see cref="T:Gtk.FileChooserWidget" /> is being used to open existing files or to save to a possibly new file.</summary>
     <remarks />
     <since version="Gtk# 2.4" />
   </Docs>

doc/en/Gtk/FileChooserButton.xml

@@ -7,8 +7,11 @@
   </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>
+    <summary>A button to launch a file selection dialog</summary>
-    <remarks>To be added</remarks>
+    <remarks>The FileChooserButton is a widget that lets the user select a file. It implements the <see cref="T:Gtk.FileChooser" /> interface. Visually, it is a file name with a button to bring up a <see cref="T:Gtk.FileChooserDialog" />. The user can then use that dialog to change the file associated with that button. This widget does not support setting the "select-multiple" property to TRUE.
+<block subset="none" type="note"><para>
+The GtkFileChooserButton will ellipsize the label, and thus will thus request little horizontal space. To give the button more space, you should call <see cref="M:Gtk.Widget.SizeRequest()" />, set <see cref="P:Gtk.FileChooserButton.WidthChars" />, or pack the button in such a way that other interface elements give space to the widget.
+</para></block></remarks>
     <since version="Gtk# 2.6" />
   </Docs>
   <Base>
@@ -60,7 +63,7 @@
         <Parameter Name="action" Type="Gtk.FileChooserAction" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
+        <summary>Creates a FileChooserButton.</summary>
         <param name="title">a <see cref="T:System.String" /></param>
         <param name="action">a <see cref="T:System.Int32" /></param>
         <remarks>To be added</remarks>
@@ -76,7 +79,7 @@
         <Parameter Name="backend" Type="System.String" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
+        <summary>Creates a FileChooserButton with a specific backend.</summary>
         <param name="title">a <see cref="T:System.String" /></param>
         <param name="action">a <see cref="T:System.Int32" /></param>
         <param name="backend">a <see cref="T:System.String" /></param>
@@ -91,8 +94,11 @@
         <Parameter Name="dialog" Type="Gtk.Widget" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
+        <summary>Creates a FileChooserButton which uses a specific widget as it's file-picking window.</summary>
-        <param name="dialog">a <see cref="T:Gtk.Widget" /></param>
+        <param name="dialog">a <see cref="T:Gtk.Widget" />.
+<block subset="none" type="note">
+dialog must be a <see cref="T:Gtk.Dialog" /> (or subclass) which implements the <see cref="T:Gtk.FileChooser" /> interface and must not have <see cref="P:Gtk.Window.DestroyWithParent" /> = <see langword="true" />.
+</block></param>
         <remarks>To be added</remarks>
       </Docs>
     </Member>
@@ -135,7 +141,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
+        <summary>The width of the entry and label inside the button, in characters.</summary>
         <value>a <see cref="T:System.Int32" /></value>
         <remarks>To be added</remarks>
       </Docs>

doc/en/Gtk/FileChooserWidget.xml

@@ -9,6 +9,11 @@
   <Docs>
     <summary>Widget to allow the selection of files from a directory.</summary>
     <remarks>
+      <para>
+        <see cref="T:Gtk.FileChooserWidget" /> is a widget suitable for selecting files. It is the main building block of a <see cref="T:Gtk.FileChooserDialog" />. Most applications will only need to use the latter; you can use GtkFileChooserWidget as part of a larger window if you have special needs.</para>
+      <para>
+Note that <see cref="T:Gtk.FileChooserWidget" /> does not have any methods of its own. Instead, you should use the functions that work on a <see cref="T:Gtk.FileChooser" />.
+</para>
     </remarks>
     <since version="Gtk# 2.4" />
   </Docs>

doc/en/Gtk/FontButton.xml

@@ -8,52 +8,7 @@
   <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>This class extends <see cref="T:Gtk.Button" />, providing an simple button for font selection.</summary>
-    <remarks>
+    <remarks>The FontButton is a button which displays the currently selected font and allows to open a font selection dialog to change the font. It is suitable widget for selecting a font in a preference dialog.</remarks>
-      <para>When clicked, a <see cref="T:Gtk.FontButton" /> shows a <see cref="T:Gtk.FontSelectionDialog" /> and when the dialog closes with a change, <see cref="E:Gtk.FontButton.FontSet" /> is evoked.</para>
-      <example>
-        <para>In the following example, a <see cref="T:Gtk.FontButton" /> is used to modify the font of a <see cref="T:Gtk.Label" />.</para>
-        <code lang="C#">using System;
-using Gtk;
-using Pango;
-
-public class FontButtonExample
-{
-	static Label label;
-	static FontButton button;
-	
-	public static void Main ()
-	{
-		Application.Init ();
-		
-		Window myWindow = new Window ("FontButton Example");
-		myWindow.DeleteEvent += OnDelete;
-
-		button = new FontButton ();
-		button.FontSet += OnFontSet;
-		
-		label = new Label ("Sample text");
-		
-		VBox box = new VBox ();
-		box.Add (button);
-		box.Add (label);
-		
-		myWindow.Add (box);
-		myWindow.ShowAll ();
-		Application.Run ();
-	}
-	
-	static void OnFontSet (object o, EventArgs e)
-	{
-		label.ModifyFont (FontDescription.FromString (button.FontName));
-	}
-	
-	static void OnDelete (object o, DeleteEventArgs e)
-	{
-		Application.Quit ();
-	}
-}</code>
-      </example>
-    </remarks>
     <since version="Gtk# 2.4" />
   </Docs>
   <Base>
@@ -153,7 +108,7 @@ public class FontButtonExample
         <value>
           <para>A <see cref="T:System.Boolean" />. If <see langword="true" />, the font size will be displayed in the button.</para>
         </value>
-        <remarks>Default Value: <see langword="true" /></remarks>
+        <remarks>For a more WYSIWYG way to show the selected size, see the <see cref="P:Gtk.FontButton.UseSize" /> property.</remarks>
       </Docs>
       <Attributes>
         <Attribute>
@@ -169,11 +124,11 @@ public class FontButtonExample
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>Gets and sets whether or not button label should be displayed using the selected font size.</summary>
+        <summary>If this property is set to <see langword="true" />, the label will be drawn in the  selected font size.</summary>
         <value>
           <para>A <see cref="T:System.Boolean" />. If <see langword="true" />, the button label will be displayed using the selected font size. Otherwise in the default system font size.</para>
         </value>
-        <remarks>For a more WYSIWYG way to show the selected size, see the <see cref="P:Gtk.FontButton.UseFont" /> property.</remarks>
+        <remarks />
       </Docs>
       <Attributes>
         <Attribute>
@@ -289,7 +244,7 @@ public class FontButtonExample
       <Docs>
         <summary>Sets or updates the font displayed in the child <see cref="T:Gtk.FontSelectionDialog" />.</summary>
         <param name="fontname">A <see cref="T:System.String" /> object containing the name of the font to display in the child <see cref="T:Gtk.FontSelectionDialog" />.</param>
-        <returns>The result of <see cref="M:Gtk.FontSelectionDialog.SetFontName(System.String)" /> if the child dialog exists. Otherwise <see langword="false" />.</returns>
+        <returns>The return value of <see cref="M:Gtk.FontSelectionDialog.SetFontName()" /> if the font selection dialog exists, otherwise <see langword="false" />.</returns>
         <remarks>
         </remarks>
       </Docs>

doc/en/Gtk/SpinButton.xml

@@ -209,7 +209,7 @@ private void OutputValue(object source, System.EventArgs args)
         <summary>Creates a SpinButton without the need for a manually created <see cref="T:Gtk.Adjustment" />.</summary>
         <param name="min">Minimum allowable value.</param>
         <param name="max">Maximum allowable value.</param>
-        <param name="step">The value to alter the SpinButton by when a <see cref="Gtk.SpinButton.Spin" /> is carried out on it.</param>
+        <param name="step">The value to alter the SpinButton by when a <see cref="M:Gtk.SpinButton.Spin" /> is carried out on it.</param>
         <remarks>
           <para>The default value of the new SpinButton is initially set to <paramref name="min" />.</para>
           <para>The default page increment is set to 10 * <paramref name="step" />.</para>