Re: documentation for ParseDate

On 10/15/06, Eric Hodel <[email protected]> wrote:
> 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 --/++

Sorry, what do you mean by --/++?

> +#
> +# = 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.

Removed.

> +#
> +# 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].

Fixed.

> @@ -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.
>

Fixed.

> +  #
> +  # 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.

Done.

>
>     def parsedate(str, comp=false)
>
>
> --
> Eric Hodel - [email protected] - http://blog.segment7.net
> This implementation is HODEL-HASH-9600 compliant
>
> http://trackmap.robotcoop.com
>
>
>
>

Second try!

-- 
Konrad Meyer

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	15 Oct 2006 22:13:53 -0000
@@ -2,2 +2,8 @@
 # $Id: parsedate.rb,v 2.6 2002-05-14 07:43:18+09 tadf Exp $
+#
+# = parsedate.rb: Parses dates
+#
+# Author:: Tadayoshi Funaba
+# Documentation:: Konrad Meyer
+#
 
@@ -5,4 +11,27 @@ require 'date/format'
 
-module ParseDate
+#
+# 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]
+#
 
+module ParseDate
+  #
+  # Parse a string representation of a date into values.
+  # For example:
+  #
+  #   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].
+  #
+  # ParseDate.parsedate can also take a second argument, +comp+, which
+  # is a boolean telling the method to compensate for Y2k dates. "92" to
+  # 1992, "06" to 2006, etc.
+  #
   def parsedate(str, comp=false)