[Mono-docs-list] CheckButton documentation

[Duncan Mak]

On Thu, 2003-02-20 at 10:23, Kevin Breit wrote:
> Hey,
> 	Attached is the CheckButton.xml file for Gtk#.  In general, it should
> be okay.  I just want to make sure before I commit.

A few things:

	* Please add your name to the Maintainer attribute in the TypeSignature
element. (with hindsight, I should have added this to the Type element,
oh well).

	* There are some typos. (missing spaces, "see:cred", instead of
"see:cref").

	* The summary should always only be one line, and short too. I think
the description in the C documentation is pretty good, "A GtkCheckButton
places a discrete GtkToggleButton next to a widget." The text there
should be placed inside the <remark> element instead.

	<summary>A CheckButton is a special type of togglebutton that
	normally is positioned next to a label.  The
	CheckButton differs from the <see cred="T:Gtk.ToggleButton"/> in
	that the CheckButton has a check inside of the box which gets toggled, while the
	ToggleButton depresses the entire button.</summary>
	<remarks><para>An alternativeto the CheckButton is the <see
	cred="T:Gtk.ToggleButton"/>.</para>/remarks>

I think this might be better:

	<summary>A GtkCheckButton places a discrete GtkToggleButton next to a
widget.</summary>
	<remarks>
	   <para>
	       A GtkCheckButton places a discrete <see
cref="T:Gtk.ToggleButton"/> next to a widget, usually a <see
cref="T:Gtk.Label"/>. See <see cref="T:Gtk.ToggleButton"/> for more
information about toggle/check buttons.
	   </para>
	</remarks>

(This text is ripped directly from the C documentation)


	* When documenting a parameter, it is not necessary to repeat the type
information, as the information is already available in the type
signature. Again, the text in the C documentation is pretty good, "label
:the text for the check button."

        <param name="label">The label displayed to the right of the CheckButton: an object of type 'string'</param>
        <returns>A Gtk# object of the type CheckButton.</returns>


	* This is not an internal constructor.

	    <Member MemberName=".ctor">
	      <MemberSignature Language="C#" Value="public CheckButton ();" />
	      <MemberType>Constructor</MemberType>
	      <ReturnValue />
	      <Parameters />
	      <Docs>
	        <summary>Internal constructor</summary>
	        <returns>A new CheckButton</returns>
	        <remarks></remarks>
	      </Docs>
	    </Member>

-- 
Duncan Mak <duncan@ximian.com>