Merge pull request #2430 from Miepee/combobox-doc

Revise documentation for ComboBox

Author: cwensley

src/Eto/Forms/Controls/CheckBoxList.cs

@@ -2,7 +2,6 @@
 using System.Collections.Generic;
 using System.Linq;
 using Eto.Drawing;
-using System.Collections;
 
 namespace Eto.Forms;
 

src/Eto/Forms/Controls/CollectionEditor.cs

@@ -1,6 +1,5 @@
 using System;
 using System.Collections.Generic;
-using System.ComponentModel;
 
 namespace Eto.Forms;
 

src/Eto/Forms/Controls/ColorPicker.cs

@@ -1,6 +1,5 @@
 using System;
 using Eto.Drawing;
-using System.ComponentModel;
 
 namespace Eto.Forms;
 

src/Eto/Forms/Controls/ComboBox.cs

@@ -1,14 +1,17 @@
 using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.ComponentModel;
 
 namespace Eto.Forms;
 
 /// <summary>
 /// Presents a combination of an editable text box and drop down to select from a list of items and enter text.
 /// </summary>
+/// <example>
+/// Here is a short example on how to create an autocompleting check box.
+/// <code>
+/// var list = new List&lt;string&gt;() { "First item", "Second item", "Third item" };
+/// var comboBox = new ComboBox() { AutoComplete = true, DataStore = list }; 
+/// </code>
+/// </example>
 [Handler(typeof(IHandler))]
 public class ComboBox : DropDown
 {
@@ -20,7 +23,7 @@ public class ComboBox : DropDown
 	public const string TextChangedEvent = "ComboBox.TextChanged";
 
 	/// <summary>
-	/// Occurs when the Text property is changed either by the user or programatically.
+	/// Occurs when the <see cref="Text"/> property is changed either by the user or programatically.
 	/// </summary>
 	public event EventHandler<EventArgs> TextChanged
 	{
@@ -31,7 +34,7 @@ public event EventHandler<EventArgs> TextChanged
 	/// <summary>
 	/// Raises the <see cref="TextChanged"/> event.
 	/// </summary>
-	/// <param name="e">Event arguments</param>
+	/// <param name="e">Event arguments.</param>
 	protected virtual void OnTextChanged(EventArgs e)
 	{
 		Properties.TriggerEvent(TextChangedEvent, this, e);
@@ -45,7 +48,7 @@ public ComboBox()
 	}
 
 	/// <summary>
-	/// Gets or sets the text of the ComboBox.
+	/// Gets or sets the text of the combo box.
 	/// </summary>
 	/// <value>The text content.</value>
 	public string Text
@@ -58,8 +61,9 @@ public string Text
 	/// Gets or sets whether the user can change the text in the combo box.
 	/// </summary>
 	/// <remarks>
-	/// When <c>true</c>, the user will still be able to select/copy the text, select items from the drop down, etc.
-	/// To disable the control, use the <see cref="Control.Enabled"/> property.
+	/// When <see langword="true"/>, the user will still be able to select/copy the text or select items from the drop down.
+	/// They will only be unable to type in different text. <br/>
+	/// To fully disable the control, use the <see cref="Control.Enabled"/> property.
 	/// </remarks>
 	public bool ReadOnly
 	{
@@ -71,9 +75,9 @@ public bool ReadOnly
 	/// Gets or sets a value indicating that the text should autocomplete when the user types in a value.
 	/// </summary>
 	/// <remarks>
-	/// The autocomplete will be based off of the items in the combo box.
+	/// The autocomplete will be based off of the available items in the combo box.
 	/// </remarks>
-	/// <value><c>true</c> to auto complete the text; otherwise, <c>false</c>.</value>
+	/// <value><see langword="true"/> to auto complete the text; otherwise, <see langword="false"/>.</value>
 	public bool AutoComplete
 	{
 		get { return Handler.AutoComplete; }
@@ -82,65 +86,49 @@ public bool AutoComplete
 
 	static readonly object callback = new Callback();
 
-	/// <summary>
-	/// Gets an instance of an object used to perform callbacks to the widget from handler implementations
-	/// </summary>
-	/// <returns>The callback instance to use for this widget</returns>
+	/// <inheritdoc/>
 	protected override object GetCallback()
 	{
 		return callback;
 	}
 
 	/// <summary>
-	/// Callback interface for the <see cref="ComboBox"/>
+	/// Callback interface for the <see cref="ComboBox"/>.
 	/// </summary>
 	public new interface ICallback : DropDown.ICallback
 	{
 		/// <summary>
-		/// Raises the text changed event.
+		/// <inheritdoc cref="ComboBox.OnTextChanged" path="/summary"/>
 		/// </summary>
+		// TODO: document parameters
 		void OnTextChanged(ComboBox widget, EventArgs e);
 	}
 
 	/// <summary>
-	/// Callback implementation for handlers of <see cref="ListControl"/>
+	/// Callback implementation for handlers of <see cref="ComboBox"/>.
 	/// </summary>
 	protected new class Callback : DropDown.Callback, ICallback
 	{
-		/// <summary>
-		/// Raises the text changed event.
-		/// </summary>
+        /// <inheritdoc cref="ICallback.OnTextChanged"/>
 		public void OnTextChanged(ComboBox widget, EventArgs e)
 		{
 			using (widget.Platform.Context)
 				widget.OnTextChanged(e);
 		}
 	}
-
-
+	
 	/// <summary>
-	/// Handler interface for the <see cref="ComboBox"/>
+	/// Handler interface for the <see cref="ComboBox"/>.
 	/// </summary>
 	public new interface IHandler : DropDown.IHandler
 	{
-		/// <summary>
-		/// Gets or sets the text of the ComboBox.
-		/// </summary>
-		/// <value>The text content.</value>
+		/// <inheritdoc cref="ComboBox.Text"/>
 		string Text { get; set; }
 
-		/// <summary>
-		/// Gets or sets the editable of ComboBox.
-		/// </summary>
+		/// <inheritdoc cref="ComboBox.ReadOnly"/>
 		bool ReadOnly { get; set; }
 
-		/// <summary>
-		/// Gets or sets a value indicating that the text should autocomplete when the user types in a value.
-		/// </summary>
-		/// <remarks>
-		/// The autocomplete will be based off of the items in the combo box.
-		/// </remarks>
-		/// <value><c>true</c> to auto complete the text; otherwise, <c>false</c>.</value>
+		/// <inheritdoc cref="ComboBox.AutoComplete"/>
 		bool AutoComplete { get; set; }
 	}
 }

src/Eto/Forms/Controls/DropDown.cs

@@ -175,10 +175,7 @@ public event EventHandler<DropDownFormatEventArgs> FormatItem
 	/// <param name="e">Event Arguments</param>
 	protected virtual void OnFormatItem(DropDownFormatEventArgs e) => Properties.TriggerEvent(FormatItemEvent, this, e);
 
-	/// <summary>
-	/// Gets the callback.
-	/// </summary>
-	/// <returns>The callback.</returns>
+	/// <inheritdoc/>
 	protected override object GetCallback() => new Callback();
 
 	/// <summary>