Re: documentation for ParseDate

On Oct 7, 2006, at 3:19 PM, Konrad Meyer wrote:

> One module, one method. See attached.
>
> I'd greatly appreciate comments, since this is my first effort; I
> mostly tried to emulate the documentation of Ostruct, which was rated
> at 10.
Index: parsedate.rb
===================================================================
RCS file: /src/ruby/lib/parsedate.rb,v
retrieving revision 1.18
diff -p -u -1 -r1.18 parsedate.rb
--- parsedate.rb        25 Aug 2006 23:06:41 -0000      1.18
+++ parsedate.rb        7 Oct 2006 22:16:41 -0000
@@ -1,3 +1,21 @@
-# parsedate.rb: Written by Tadayoshi Funaba 2001, 2002
-# $Id: parsedate.rb,v 2.6 2002-05-14 07:43:18+09 tadf Exp $

Don't remove the $Id$ or the dates.  Hide them in --/++

+#
+# = parsedate.rb: Parses dates
+#
+# Author:: Tadayoshi Funaba
+# Documentation:: Konrad Meyer
+#
+# ParseDate munches on a date and turns it into an array of values.
+#
+

This whitespace will cause the lines above to not be included.  Is  
that what you intend?  If so, I think the munching sentance is  
redundant.
+#
+# ParseDate converts a date into an array of values.
+# For example:
+#
+#   require 'parsedate'
+#
+#   ParseDate.parsedate "Tuesday, July 6th, 2007, 18:35:20 UTC"
+#   # => [2007, 7, 6, 18, 35, 20, "UTC", 2]
+#
+# The order is of the form [year, month, day of month, hour, minute,  
second,
+# timezone, day of the week].

@@ -6,3 +24,23 @@ require 'date/format'
module ParseDate
-
+  #
+  # Parse a string representation of a date into values.
+  # For example:
+  #
+  #   require 'parsedate'
+  #
+  #   ParseDate.parsedate "Tuesday, July 5th, 2007, 18:35:20 UTC"
+  #   # => [2007, 7, 5, 18, 35, 20, "UTC", 2]
+  #
+  # The order is of the form [year, month, day of month, hour, minute,
+  # second, timezone, day of week].

This documentation is redundant with the module documentation.  I  
think it the require should be removed from here and the order  
removed from the module documentation.
+  #
+  # ParseDate.parsedate can also take a second argument, +comp+, which
+  # is a boolean telling the method to compensate for dates with years
+  # expressed as two digits. Example:
+  #
+  #   require 'parsedate'
+  #
+  #   ParseDate.parsedate "Mon Dec 25 00 06:53:24 UTC", true
+  #   # => [2000, 12, 25, 6, 53, 24, "UTC", 1]
+  #

I think the example is redundant here, and the nature of the  
compensation should be described.  Also, remove the require.
   def parsedate(str, comp=false)


--
Eric Hodel - drbrain@xxxxxxxxxxxx - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com