From 884418c3af50c78272263ba1e959d973ef1ec1e4 Mon Sep 17 00:00:00 2001
From: Mischa POSLAWSKY <perl@shiar.org>
Date: Fri, 17 Oct 2008 00:00:03 +0000
Subject: [PATCH] more detailed method documentation

---
 lib/HTML/Form/Simple.pm | 68 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 60 insertions(+), 8 deletions(-)

diff --git a/lib/HTML/Form/Simple.pm b/lib/HTML/Form/Simple.pm
index f96149f..18be571 100644
--- a/lib/HTML/Form/Simple.pm
+++ b/lib/HTML/Form/Simple.pm
@@ -252,25 +252,69 @@ HTML::Form::Simple - Generate HTML form elements
 
 =head1 DESCRIPTION
 
+Set up a form object with new().  The HTML for the opening and closing
+C<< <form> >> tags are returned by the start() and stop() methods.
+
+The L<hidden>, L<text>, L<select>, L<radio>, and L<check> methods all
+correspond to various input types.  The first argument is always the mandatory
+name, and a hash ref as the last argument can optionally be provided for
+additional attributes/options.  Everything is properly escaped.
+
 =over
 
 =item C<hidden>
 
-	$input->hidden(name => 'value');
+Returns the HTML for a simple C<< <input type="hidden"> >> with specified name
+and value (both are required by HTML specs).
+
+	$input->hidden('name', 'value');
+
+As with all methods, a final hash ref can be given to add further attributes.
+While rarely needed in this case, it can also be used as an override or
+alternative to value and name:
+
+	$input->hidden({name => 'name', value => 'value'})
 
 =item C<text>
 
-	$input->text(name => 'default');
+The common C<< <input type="text"> >>.
+
+	$input->text('name', 'default');
+
+If the I<rows> option is set, substitutes a similarly set up C<< <textarea> >>:
+
+	$input->text('name', 'default', {rows => 4});
 
 =item C<select>
 
-	$input->select(name => ['option'], 'default');
+	$input->select('name', ['option'], 'default');
+
+Provides C<< <select><option> >> dropdown by default, but can also output
+multiple C<< <input> >> tags if a I<type> is provided:
+
+	$input->select('name', ['1'], {type => 'checkbox'});
+
+In scalar context, options are joined together by C<$,> (C<$OUTPUT_FIELD_SEPARATOR>).
+Otherwise a list of tags is returned.
+
+Each option can be given as either a simple string containing its I<value>,
+or a hash ref with custom attributes.
+When there's no parent tag (only C<< <input> >>s), a fourth parameter can
+provide common options which will be inherited by each element.  Otherwise,
+options will apply to either the C<< <select> >> or an C<< <option> >>.
+
+The default value (either as a third scalar parameter, or with the general
+I<value> option) will be matched to the value of each option, and if equal,
+its I<selected> or I<checked> attribute will be set as appropriate.
 
 =item C<radio>
 
-	$input->radio(name => ['option'], ['option label'], 'default');
+In fact just a shorthand to L<select> with a preset type of I<radio>, but takes
+an additional third argument to easily set the label for each option:
+
+	$input->radio('name', ['option'], ['option label'], 'default');
 
-eq
+This would be the same as saying:
 
 	$input->radio(
 		'name',
@@ -280,11 +324,19 @@ eq
 
 =item C<check>
 
-	$input->check(name => ['label', 'second option'], [0, 1]);
+Also a L<select> shorthand, but with a I<checkbox> type.
+Instead of values, the second argument specifies option I<label>s.
+The values by default are set to an auto-incrementing number starting with 1.
+
+Furthermore, the I<checked> status for each option can be specified by a third
+argument.  Either a single boolean value defining all rows, or an array ref
+with the value for each row in order.
+
+	$input->check('name', ['label', 'second option'], [0, 1]);
 
-eq
+Or more descriptive but identical:
 
-	$input->check(name => [
+	$input->check('name', [
 		{label => 'label',         value => 1, checked => 0},
 		{label => 'second option', value => 2, checked => 1},
 	]);
-- 
2.30.0