Project

General

Profile

Bug #5402

Enhancing documentation for Time extension in stlib

Added by semmons99 (Shane Emmons) over 7 years ago. Updated over 7 years ago.

Status:
Closed
Priority:
Normal
Target version:
ruby -v:
trunk
Backport:
[ruby-core:39929]

Description

As part of Mendicant Universities MRI Documentation Week, I've enhanced the documentation for the Time extension module in stdlib.


Files

Associated revisions

Revision 0d900cec
Added by drbrain (Eric Hodel) over 7 years ago

  • time.c (Init_Time): Improve Time documentation. Patch by Shane Emmons. [Ruby 1.9 - Bug #5404]
  • lib/time.rb: Improve time.rb documentation including Time.strptime. Patch by Shane Emmons. [Ruby 1.9 - Bug #5402]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@33414 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

Revision 33414
Added by drbrain (Eric Hodel) over 7 years ago

  • time.c (Init_Time): Improve Time documentation. Patch by Shane Emmons. [Ruby 1.9 - Bug #5404]
  • lib/time.rb: Improve time.rb documentation including Time.strptime. Patch by Shane Emmons. [Ruby 1.9 - Bug #5402]

Revision 33414
Added by drbrain (Eric Hodel) over 7 years ago

  • time.c (Init_Time): Improve Time documentation. Patch by Shane Emmons. [Ruby 1.9 - Bug #5404]
  • lib/time.rb: Improve time.rb documentation including Time.strptime. Patch by Shane Emmons. [Ruby 1.9 - Bug #5402]

Revision 33414
Added by drbrain (Eric Hodel) over 7 years ago

  • time.c (Init_Time): Improve Time documentation. Patch by Shane Emmons. [Ruby 1.9 - Bug #5404]
  • lib/time.rb: Improve time.rb documentation including Time.strptime. Patch by Shane Emmons. [Ruby 1.9 - Bug #5402]

Revision 33414
Added by drbrain (Eric Hodel) over 7 years ago

  • time.c (Init_Time): Improve Time documentation. Patch by Shane Emmons. [Ruby 1.9 - Bug #5404]
  • lib/time.rb: Improve time.rb documentation including Time.strptime. Patch by Shane Emmons. [Ruby 1.9 - Bug #5402]

Revision 33414
Added by drbrain (Eric Hodel) over 7 years ago

  • time.c (Init_Time): Improve Time documentation. Patch by Shane Emmons. [Ruby 1.9 - Bug #5404]
  • lib/time.rb: Improve time.rb documentation including Time.strptime. Patch by Shane Emmons. [Ruby 1.9 - Bug #5402]

Revision 33414
Added by drbrain (Eric Hodel) over 7 years ago

  • time.c (Init_Time): Improve Time documentation. Patch by Shane Emmons. [Ruby 1.9 - Bug #5404]
  • lib/time.rb: Improve time.rb documentation including Time.strptime. Patch by Shane Emmons. [Ruby 1.9 - Bug #5402]

History

Updated by drbrain (Eric Hodel) over 7 years ago

  • Target version set to 1.9.4

Since the comment from time.c and time.rb will be combined for ri output the introductory sentence should be reworded. Something like:

When 'time' is required, Time is extended with additional methods for parsing and converting Times

Unqualified method names should be prefixed with # instead of surrounded by ++, qualified names don't need ++ either and classes should not be surrounded with ++. This allows rdoc to link methods and classes to their specific documentation:

# The easiest way to create a new time object is to use either #parse
# #strptime. Each uses Date.parse and Date.strptime to create a new instance of Time.

For Time.parse, I think an unambiguous date like 2010-10-31 should be used so the month and day position are easy to determine.

The strptime format explanation should be moved to Time.strptime and the list should use :: instead of - as the separator.

Updated by semmons99 (Shane Emmons) over 7 years ago

I've tried to implement all your suggestions. Here's an updated patch. Let me know if there's anything else you'd like changed.

#3

Updated by drbrain (Eric Hodel) over 7 years ago

  • Status changed from Open to Closed
  • % Done changed from 0 to 100

This issue was solved with changeset r33414.
Shane, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.


  • time.c (Init_Time): Improve Time documentation. Patch by Shane Emmons. [Ruby 1.9 - Bug #5404]
  • lib/time.rb: Improve time.rb documentation including Time.strptime. Patch by Shane Emmons. [Ruby 1.9 - Bug #5402]

Also available in: Atom PDF