Issue #7326 has been reported by bt (Bernd Homuth). ---------------------------------------- Bug #7326: Time.c doc improvements https://bugs.ruby-lang.org/issues/7326 Author: bt (Bernd Homuth) Status: Open Priority: Normal Assignee: drbrain (Eric Hodel) Category: DOC Target version: ruby -v: 1.9.3 I tried to improve some parts of the documentation. Mainly I changed +Time+ for classes and _time_ for objects. I fixed some typos and probably introduced new ones. Please check carefully.
on 2012-11-10 18:44
on 2012-11-10 22:28
Issue #7326 has been updated by bt (Bernd Homuth). Actually, I'm not really happy with my "improvements". After looking through more classes there is inconsistency everywhere and it seems every class has its own style. Maybe there should be some API documentation guideline first. I checked the Rails guidelines but don't think they cover everything: http://edgeguides.rubyonrails.org/api_documentatio... ---------------------------------------- Bug #7326: Time.c doc improvements https://bugs.ruby-lang.org/issues/7326#change-32758 Author: bt (Bernd Homuth) Status: Open Priority: Normal Assignee: drbrain (Eric Hodel) Category: DOC Target version: ruby -v: 1.9.3 I tried to improve some parts of the documentation. Mainly I changed +Time+ for classes and _time_ for objects. I fixed some typos and probably introduced new ones. Please check carefully.
on 2012-11-12 03:25
Issue #7326 has been updated by zzak (Zachary Scott). Assignee changed from drbrain (Eric Hodel) to zzak (Zachary Scott) Target version set to 2.0.0 ---------------------------------------- Bug #7326: Time.c doc improvements https://bugs.ruby-lang.org/issues/7326#change-32796 Author: bt (Bernd Homuth) Status: Open Priority: Normal Assignee: zzak (Zachary Scott) Category: DOC Target version: 2.0.0 ruby -v: 1.9.3 I tried to improve some parts of the documentation. Mainly I changed +Time+ for classes and _time_ for objects. I fixed some typos and probably introduced new ones. Please check carefully.
on 2012-11-12 05:31
Issue #7326 has been updated by rohitarondekar (Rohit Arondekar). =begin Made a quick pass through the patch and the following stood out: >> ((*The idea is taken from Perl:*)) I would prefer "The idea is borrowed from Perl:" >> ((*The first DST is at 1916 in German. So we don't need to care DST before that.*)) I would prefer "DST was used for the first time by Germany starting in 1916" and "Therefore we don't check for DST prior to 1916" Also IMHO I think it would have been better if the patch was split into two ― one only for formatting changes and another for corrections. Don't do it because I said so! I just think it would have made reviewing the patch easier. :) I agree on CRuby needing a API Documentation guideline. The reasons are obvious, it will make editing and adding docs much easier for both newcomers as well as existing contributors. However how do you go about writing a documentation guide for a programming language? :) I'll try to find if other programming languages have such a guide. =end ---------------------------------------- Bug #7326: Time.c doc improvements https://bugs.ruby-lang.org/issues/7326#change-32802 Author: bt (Bernd Homuth) Status: Open Priority: Normal Assignee: zzak (Zachary Scott) Category: DOC Target version: 2.0.0 ruby -v: 1.9.3 I tried to improve some parts of the documentation. Mainly I changed +Time+ for classes and _time_ for objects. I fixed some typos and probably introduced new ones. Please check carefully.
on 2012-11-12 08:18
Issue #7326 has been updated by bt (Bernd Homuth). @rohitarondekar thank you for the comments and welcome to ruby bugs :) > I would prefer "The idea is borrowed from Perl:" yes, sounds better, you're right. > > >> ((*The first DST is at 1916 in German. > So we don't need to care DST before that.*)) > > I would prefer "DST was used for the first time by Germany starting in 1916" and "Therefore we don't check for DST prior to 1916" Doesn't really matter if it was used in Germany or elsewhere, should be rephrased altogether. > Also IMHO I think it would have been better if the patch was split into two ― one only for formatting changes and another for corrections. Don't do it because I said so! I just think it would have made reviewing the patch easier. :) > > I agree on CRuby needing a API Documentation guideline. The reasons are obvious, it will make editing and adding docs much easier for both newcomers as well as existing contributors. However how do you go about writing a documentation guide for a programming language? :) I'll try to find if other programming languages have such a guide. yes to both, zzak sent me the link to this: http://bugs.ruby-lang.org/projects/ruby/wiki/DocumenterHowTo so there is some documentation available. Needs some clarifications, though. ---------------------------------------- Bug #7326: Time.c doc improvements https://bugs.ruby-lang.org/issues/7326#change-32811 Author: bt (Bernd Homuth) Status: Open Priority: Normal Assignee: zzak (Zachary Scott) Category: DOC Target version: 2.0.0 ruby -v: 1.9.3 I tried to improve some parts of the documentation. Mainly I changed +Time+ for classes and _time_ for objects. I fixed some typos and probably introduced new ones. Please check carefully.
on 2012-11-14 05:55
Issue #7326 has been updated by zzak (Zachary Scott). The formatting looks good, except you shouldn't wrap classes in anything, such as ArgumentError or Time and Time#to_f This allow rdoc to properly link these objects. ---------------------------------------- Bug #7326: Time.c doc improvements https://bugs.ruby-lang.org/issues/7326#change-32893 Author: bt (Bernd Homuth) Status: Open Priority: Normal Assignee: zzak (Zachary Scott) Category: DOC Target version: 2.0.0 ruby -v: 1.9.3 I tried to improve some parts of the documentation. Mainly I changed +Time+ for classes and _time_ for objects. I fixed some typos and probably introduced new ones. Please check carefully.
on 2012-11-18 12:22
Issue #7326 has been updated by bt (Bernd Homuth). File time_docs_2.diff added In contrast to the guidelines I have: _arguments_, _object_ and _other_object_ (also _self_) Monospaced only for return values: +nil and +true+ What about class methods: Time::new vs Time#new vs Time.new? Method references should be complete or abbreviated: Time#to_a vs #to_a If we can decide on a format I can go through the other classes as well. diff is just for review, not yet split. ---------------------------------------- Bug #7326: Time.c doc improvements https://bugs.ruby-lang.org/issues/7326#change-33052 Author: bt (Bernd Homuth) Status: Open Priority: Normal Assignee: zzak (Zachary Scott) Category: DOC Target version: 2.0.0 ruby -v: 1.9.3 I tried to improve some parts of the documentation. Mainly I changed +Time+ for classes and _time_ for objects. I fixed some typos and probably introduced new ones. Please check carefully.
on 2012-11-20 04:44
Issue #7326 has been updated by zzak (Zachary Scott). If you can separate typo/grammer changes from formatting, it will be much easier for me to review and more likely to commit. ---------------------------------------- Bug #7326: Time.c doc improvements https://bugs.ruby-lang.org/issues/7326#change-33153 Author: bt (Bernd Homuth) Status: Open Priority: Normal Assignee: zzak (Zachary Scott) Category: DOC Target version: 2.0.0 ruby -v: 1.9.3 I tried to improve some parts of the documentation. Mainly I changed +Time+ for classes and _time_ for objects. I fixed some typos and probably introduced new ones. Please check carefully.
on 2012-11-20 05:09
Issue #7326 has been updated by drbrain (Eric Hodel).
=begin
Arguments should be surrounded by "+", not "_". In Time.at,
(({+seconds+})), (({+seconds_with_frac+})) and
(({+microseconds_with_frac+})) are preferred.
Otherwise, a quick scan makes me think this patch is good.
For reference purposes, methods will be linked in the same class if they
have an "_" or them, so (({Time#to_s})) and (({#to_s})) and (({to_s}))
would all link to the same place. A full name like (({Array#join}))
should be used when referring to a method external to the current class.
If a method doesn't have an "_" like (({Time#sec})) you need to prefix
it with an "#". (({Time#sec})) and (({#sec})) would both link to the
same place, but (({sec})) would not be linked.
Similarly, for class methods without "_", prefix the method with "::".
When using a full name, if the method is unambiguous, a "." will also
work. (({Time.sec})) will link to (({Time#sec}))
=end
----------------------------------------
Bug #7326: Time.c doc improvements
https://bugs.ruby-lang.org/issues/7326#change-33155
Author: bt (Bernd Homuth)
Status: Open
Priority: Normal
Assignee: zzak (Zachary Scott)
Category: DOC
Target version: 2.0.0
ruby -v: 1.9.3
I tried to improve some parts of the documentation. Mainly I changed
+Time+ for classes and _time_ for objects. I fixed some typos and
probably introduced new ones. Please check carefully.
on 2012-11-24 11:39
Issue #7326 has been updated by bt (Bernd Homuth). File time_patch0001.diff added File time_patch0002.diff added File time_patch0003.diff added See my three patches (time_patch000x.diff), first one for typos etc, second one for format changes and third one for more substantial changes to the docs. ---------------------------------------- Bug #7326: Time.c doc improvements https://bugs.ruby-lang.org/issues/7326#change-33812 Author: bt (Bernd Homuth) Status: Open Priority: Normal Assignee: zzak (Zachary Scott) Category: DOC Target version: 2.0.0 ruby -v: 1.9.3 I tried to improve some parts of the documentation. Mainly I changed +Time+ for classes and _time_ for objects. I fixed some typos and probably introduced new ones. Please check carefully.
on 2012-11-24 23:02
Issue #7326 has been updated by bt (Bernd Homuth). File time_patch0004.diff added After going over the file one last time I found a couple of lines I've missed. ---------------------------------------- Bug #7326: Time.c doc improvements https://bugs.ruby-lang.org/issues/7326#change-33828 Author: bt (Bernd Homuth) Status: Open Priority: Normal Assignee: zzak (Zachary Scott) Category: DOC Target version: 2.0.0 ruby -v: 1.9.3 I tried to improve some parts of the documentation. Mainly I changed +Time+ for classes and _time_ for objects. I fixed some typos and probably introduced new ones. Please check carefully.
Enable email notification
Enable multi-page viewPlease log in before posting. Registration is free and takes only a minute.
Existing account
(Switch to SSL-encrypted connection)
NEW: Do you have a Google/GoogleMail or Yahoo account? No registration required!
Log in with Google account | Log in with Yahoo account
Log in with Google account | Log in with Yahoo account
No account? Register here.