search

ruby / date

A subclass of Object includes Comparable module for handling dates.
Other
73 stars 38 forks source link

[DOC] New doc about Julian/Gregorian #70

Closed BurdetteLamar closed 2 years ago

BurdetteLamar commented 2 years ago

Adding a new free-standing doc about Julian and Gregorian calendars, also covering the argument start that's used by some methods in Date.

The goal is to push discussion of calendars and start out of the general discussion, where they are of little interest to many (most?) users. Instead, links would take the reader off-page, when relevant.

Also: corrects two errors in date_core.c. (If this PR is rejected, I'll put up these corrections separately.)

BurdetteLamar commented 2 years ago

I'm in favor of this change but why not directly change the documentation in the Date class rather than creating a separate document for this change? Many parts of the calendars.rdoc file already exists in the documentation for the Date class so this duplicates the existing documentation.

Sorry I was not more clear about what I'm trying to do.

The problem I see is that in reading the overview of the Date class, the reader comes to the large and complicated section "Argument start", which I think is irrelevant to most users. (How many applications deal with dates going back centuries?)

I think this material should not be in the overview, but should instead be in a separate doc that gets link to from each relevant method doc.

I intend to remove that section from the overview, and to change the links to point to the section in the new doc.

Does it make better sense to go ahead with those additional changes in this PR?

peterzhu2118 commented 2 years ago

I see, that makes sense. I think it would also make sense to remove that part in the class doc for Date in the this PR so that we don't end up with duplicate documentation.

BurdetteLamar commented 2 years ago

I see, that makes sense. I think it would also make sense to remove that part in the class doc for Date in the this PR so that we don't end up with duplicate documentation.

Done.

BurdetteLamar commented 2 years ago

Can you also add the doc directory into the .document file so that it's included when generating RDoc.

Done.

We also need to add to ruby/tool/sync_default_gems.rb.

peterzhu2118 commented 2 years ago

I think we should update ruby/tool/sync_default_gems.rb before merging this PR so that it syncs this PR to ruby/ruby.

BurdetteLamar commented 2 years ago

Thanks, @nobu. I will look into these things.

nobu commented 2 years ago

@BurdetteLamar I removed obviously wrong descriptions for now. Feel free to improve.