Documentation contributions from kevin.eeckman@gmail.com

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

doc/en/Gtk/Button.xml

@@ -387,16 +387,15 @@ public class ButtonApp  {
       <Docs>
         <summary>Creates a new <see cref="T:Gtk.Button" /> containing the image and text from a stock item.</summary>
         <param name="stock_id">a <see cref="T:System.String" /></param>
-        <remarks>The valid names of Stock items can be found in the <see cref="T:Gtk.Stock" /> class.
+        <remarks>The valid names of Stock items can be found in the <see cref="T:Gtk.Stock" /> class. If <paramref name="stock_id" /> is unknown, then it will be treated as a simple label.
 
 
 <para>
-This for example creates a stock OK button:
+This for example creates a stock OK button. It sets a localized label, a standard icon (choosed from your GTK theme), and the appropriate keyboard accelerator: 
 </para><example>
             <code lang="C#">
      Button b = new Button (Stock.Ok);
-  </code>
+  </code></example></remarks>
-          </example></remarks>
       </Docs>
     </Member>
     <Member MemberName="GType">

doc/en/Gtk/FileChooserDialog.xml

@@ -7,40 +7,34 @@
   </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>A dialog box for choosing files.</summary>
+    <summary>
+      <see cref="T:Gtk.FileChooserDialog" /> is a dialog box suitable for use with "File/Open" or "File/Save as" commands. This widget works by putting a <see cref="T:Gtk.FileChooserWidget" /> inside a <see cref="T:Gtk.Dialog" />. It exposes the <see cref="T:Gtk.FileChooser" /> interface, so you can use all of the <see cref="T:Gtk.FileChooser" /> functions on the file chooser dialog as well as those for <see cref="T:Gtk.Dialog" />.</summary>
     <remarks>Similar to <see cref="T:Gtk.FileChooserWidget" /> but in a dialog.
 
-<para /><example>
+
+<para> Typical usage. In the simplest of cases, you can use the following code to select a file for opening: 
+<example>
           <code lang="C#">
-static string Open (FileChooserAction action)
+public class MainWindow: Gtk.Window {
-{
-        string title = Catalog.GetString ("Open");
 	
-        if (action == FileChooserAction.SelectFolder)
+	protected virtual void OnBtnLoadFileClicked(object sender, System.EventArgs e)
-                title = Catalog.GetString ("Select Folder");
+	{
+		Gtk.FileChooserDialog fc=
+		new Gtk.FileChooserDialog("Choose the file to open",
+		                            this,
+		                            FileChooserAction.Open,
+		                            "Cancel",ResponseType.Cancel,
+		                            "Open",ResponseType.Accept);
 
-        FileChooserDialog chooser = new FileChooserDialog (title,
+		if (fc.Run() == (int)ResponseType.Accept) 
-                                                           window,
+		{
-                                                           action);
+			System.IO.FileStream file=System.IO.File.OpenRead(fc.Filename);
-
+			file.Close();
-        chooser.AddButton (Stock.Cancel, ResponseType.Cancel);
-        chooser.AddButton (Stock.Open, ResponseType.Ok);
-
-        chooser.SetUri (uri.ToString ());
-        int response = chooser.Run ();
-
-	string ret = null;
-
-        if ((ResponseType) response == ResponseType.Ok) {
-                ret = chooser.Uri;
 		}
-
+		//Don't forget to call Destroy() or the FileChooserDialog window won't get closed.
-        chooser.Destroy ();
+		fc.Destroy();
-	return ret;
+	}
-}
+  </code></example></para></remarks>
-
-  </code>
-      </example></remarks>
     <since version="Gtk# 2.4" />
   </Docs>
   <Base>
@@ -1001,10 +995,10 @@ static string Open (FileChooserAction action)
       <Docs>
         <summary>Creates a file chooser dialog.</summary>
         <param name="title">a title <see cref="T:System.String" /></param>
-        <param name="parent">a parent <see cref="T:Gtk.Window" /> for the dialog, or <see langword="null" />.</param>
+        <param name="parent">a parent <see cref="T:Gtk.Window" /> for the dialog, or <see langword="null" />. See <see cref="P:Gtk.Window.TransientFor" />.</param>
         <param name="action">an action, for example save or open.</param>
-        <param name="button_data">a list of button text/response pairs for buttons to be added to the dialog, if desired.</param>
+        <param name="button_data">a list of button text/response pairs for buttons to be added to the dialog, if desired. The pair format is <see cref="T:System.String" />, <see cref="T:Gtk.ResponseType" /> (see an example in overview section of <see cref="T:Gtk.FileChooserDialog" />)</param>
-        <remarks />
+        <remarks>By default, a <see cref="T:Gtk.FileChooserDialog" /> comes with no buttons, so you'd better provide at least the most basics one (Save/Cancel or Open/Cancel) or your user won't be able to do anything apart from closing the dialog ( closing the dialog returns <see cref="T:ResponseType" />.None )</remarks>
       </Docs>
     </Member>
     <Member MemberName=".ctor">

doc/en/Gtk/Label.xml

@@ -335,8 +335,7 @@
       <Docs>
         <summary>The text from a label widget including any embedded underlines indicating mnemonics and Pango markup.</summary>
         <value>The text of the label widget.</value>
-        <remarks>
+        <remarks>You can include markup tags to change your text appearance. See <see cref="P:Gtk.Label.UseMarkup" /> for more information.</remarks>
-        </remarks>
       </Docs>
       <Attributes>
         <Attribute>
@@ -437,9 +436,56 @@
       <Parameters>
       </Parameters>
       <Docs>
-        <summary>Whether the label's text is interpreted as marked up with the Pango text markup language.</summary>
+        <summary>Whether the label's text is interpreted as marked up with the Pango text markup language ( more information at http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html ).</summary>
-        <value />
+        <value>
-        <remarks />
+          <see langword="true" /> if the label's text should be parsed for markup</value>
+        <remarks>Here are a few examples of the markup you can use:
+<list type="table">
+            <listheader>
+              <term>Tag</term>
+              <description>Description</description>
+            </listheader>
+            <item>
+              <term>&lt;b&gt;</term>
+              <description>Bold</description>
+            </item>
+            <item>
+              <term>&lt;big&gt;</term>
+              <description>Makes font relatively larger</description>
+            </item>
+            <item>
+              <term>&lt;i&gt;</term>
+              <description>Italic</description>
+            </item>
+            <item>
+              <term>&lt;s&gt;</term>
+              <description>Strikethrough</description>
+            </item>
+            <item>
+              <term>&lt;sub&gt;</term>
+              <description>Subscript</description>
+            </item>
+            <item>
+              <term>&lt;sup&gt;</term>
+              <description>Superscript</description>
+            </item>
+            <item>
+              <term>&lt;small&gt;</term>
+              <description>Makes font relatively smaller</description>
+            </item>
+            <item>
+              <term>&lt;tt&gt;</term>
+              <description>Monospace font</description>
+            </item>
+            <item>
+              <term>&lt;u&gt;</term>
+              <description>Underline</description>
+            </item></list><example>
+            <code lang="C#">
+	Gtk.Label label = new Gtk.Label();
+	label.LabelProp = "The brown &lt;u&gt;fox&lt;/u&gt; etc. and the &lt;big&gt;lazy&lt;/big&gt; dog";
+	label.UseMarkup = true;
+  </code></example></remarks>
       </Docs>
       <Attributes>
         <Attribute>