some documentation for Timeish inputs, fixes #589

lib/formtastic/inputs/base/timeish.rb

@@ -1,6 +1,90 @@
 module Formtastic
   module Inputs
     module Base
+      # Timeish inputs (`:date`, `:datetime`, `:time`) are similar to the Rails date and time 
+      # helpers (`date_select`, `datetime_select`, `time_select`), rendering a series of `<select>`
+      # tags for each fragment (year, month, day, hour, minute, seconds). The fragments are then 
+      # re-combined to a date by ActiveRecord through multi-parameter assignment.
+      #
+      # The mark-up produced by Rails is simple but far from ideal, with no way to label the 
+      # individual fragments for accessibility, no fieldset to group the related fields, and no
+      # legend describing the group. Formtastic addresses this within the standard `<li>` wrapper 
+      # with a `<fieldset>` with a `<legend>` as a label, followed by an ordered list (`<ol>`) of 
+      # list items (`<li>`), one for each fragment (year, month, ...). Each `<li>` fragment contains
+      # a `<label>` (eg "Year") for the fragment, and a `<select>` containing `<option>`s (eg a 
+      # range of years).
+      #
+      # In the supplied formtastic.css file, the resulting mark-up is styled to appear a lot like a
+      # standard Rails date time select by:
+      #
+      # * styling the legend to look like the other labels (to the left hand side of the selects)
+      # * floating the `<li>` fragments against each other as a single line
+      # * hiding the `<label>` of each fragment with `display:none`
+      #
+      # @example `:date` input with full form context and sample HTMl output
+      #
+      #   <%= semantic_form_for(@post) do |f| %>
+      #     <%= f.inputs do %>
+      #       ...
+      #       <%= f.input :publish_at, :as => :date %>
+      #     <% end %>
+      #   <% end %>
+      #
+      #   <form...>
+      #     <fieldset class="inputs">
+      #       <ol>
+      #         <li class="date">
+      #           <fieldset class="fragments">
+      #             <ol class="fragments-group">
+      #               <li class="fragment">
+      #                 <label for="post_publish_at_1i">Year</label>
+      #                 <select id="post_publish_at_1i" name="post[publish_at_1i]">...</select>
+      #               </li>
+      #               <li class="fragment">
+      #                 <label for="post_publish_at_2i">Month</label>
+      #                 <select id="post_publish_at_2i" name="post[publish_at_2i]">...</select>
+      #               </li>
+      #               <li class="fragment">
+      #                 <label for="post_publish_at_3i">Day</label>
+      #                 <select id="post_publish_at_3i" name="post[publish_at_3i]">...</select>
+      #               </li>
+      #             </ol>
+      #           </fieldset>
+      #         </li>
+      #       </ol>
+      #     </fieldset>
+      #   </form>
+      #       
+      #
+      # @example `:time` input
+      #   <%= f.input :publish_at, :as => :time %>
+      #
+      # @example `:datetime` input
+      #   <%= f.input :publish_at, :as => :datetime %>
+      #
+      # @example Change the labels for each fragment
+      #   <%= f.input :publish_at, :as => :date, :labels => { :year => "Y", :month => "M", :day => "D" }  %>
+      #
+      # @example Skip a fragment (defaults to 1, skips all following fragments)
+      #   <%= f.input :publish_at, :as => :datetime, :discard_minute => true  %>
+      #   <%= f.input :publish_at, :as => :datetime, :discard_hour => true  %>
+      #   <%= f.input :publish_at, :as => :datetime, :discard_day => true  %>
+      #   <%= f.input :publish_at, :as => :datetime, :discard_month => true  %>
+      #   <%= f.input :publish_at, :as => :datetime, :discard_year => true  %>
+      #
+      # @example Change the order
+      #   <%= f.input :publish_at, :as => :date, :order => [:month, :day, :year]  %>
+      #
+      # @example Include seconds with times (excluded by default)
+      #   <%= f.input :publish_at, :as => :time, :include_seconds => true %>
+      #
+      # @example Specify if there should be a blank option at the start of each select or not
+      #   <%= f.input :publish_at, :as => :time, :include_blank=> true %>
+      #   <%= f.input :publish_at, :as => :time, :include_blank=> false %>
+      #
+      # @todo Document i18n
+      # @todo Check what other Rails options are supported (`start_year`, `end_year`, `use_month_numbers`, `use_short_month`, `add_month_numbers`, `prompt`), write tests for them, and otherwise support them
+      # @todo Could we take the rendering from Rails' helpers and inject better HTML in and around it rather than re-inventing the whee?
       module Timeish
 
         def to_html

lib/formtastic/inputs/date_input.rb

@@ -1,5 +1,7 @@
 module Formtastic
   module Inputs
+    # Outputs a series of select boxes for the fragments that make up a date (year, month, day).
+    #
     # @see Formtastic::Inputs::Timeish Timeish module for documetation of date, time and datetime input options.
     class DateInput 
       include Base

lib/formtastic/inputs/datetime_input.rb

@@ -1,5 +1,8 @@
 module Formtastic
   module Inputs
+
+    # Outputs a series of select boxes for the fragments that make up a date and time (year, month, day, hour, minute, second).
+    #
     # @see Formtastic::Inputs::Timeish Timeish module for documetation of date, time and datetime input options.
     class DatetimeInput 
       include Base

lib/formtastic/inputs/time_input.rb

@@ -1,5 +1,7 @@
 module Formtastic
   module Inputs
+    # Outputs a series of select boxes for the fragments that make up a time (hour, minute, second).
+    #
     # @see Formtastic::Inputs::Timeish Timeish module for documetation of date, time and datetime input options.
     class TimeInput 
       include Base