Ruby for the wrong reason

[James Edward Gray II]

I have suggested a better solution in the past, and I'll suggest it
again: open up the ruby docs to user comments like php does. If the
ruby community wants to continue with the worst docs I've ever seen,
then so be it.

Well, they Ruby Core team does take patches.

James Edward Gray II

 

[Michael W. Ryder]

Amazingly wrong, yeah:

Not at all:

1) $ri Date::strptime

--------------------------------------------------------- Date::strptime
Date::strptime(str='-4712-01-01', fmt='%F', sg=ITALY)
------------------------------------------------------------------------
Create a new Date object by parsing from a String according to a
specified format.

+str+ is a String holding a date representation. +fmt+ is the
format that the date is in. See date/format.rb for details on
supported formats.

The default +str+ is '-4712-01-01', and the default +fmt+ is '%F',
which means Year-Month-Day_of_Month. This gives Julian Day Number
day 0.

+sg+ specifies the Day of Calendar Reform.

An ArgumentError will be raised if +str+ cannot be parsed.
-----------------------------

Good luck finding and then digging through the **source code** of
format.rb to locate anything on the format specifiers.


2) $ri Date#strftime

---------------------------------------------------------- Date#strftime
strftime(fmt='%F')
------------------------------------------------------------------------
(no description...)



And from the official Standard Library Documentation for 'date':

1)
strptime(str='-4712-01-01', fmt='%F', sg=ITALY)
----------------------------------------

Create a new Date object by parsing from a String according to a
specified format.

str is a String holding a date representation. fmt is the format that
the date is in. See date/format.rb for details on supported formats.

The default str is ’-4712-01-01’, and the default fmt is ’%F’, which
means Year-Month-Day_of_Month. This gives Julian Day Number day 0.

sg specifies the Day of Calendar Reform.

An ArgumentError will be raised if str cannot be parsed.
=================


2)
strftime(fmt='%F')
--------------
[Source]

That last one is a real doozy--and quite typical of ruby Standard
Library documentation.

Or you could just use the Standard C Library documentation. I don't
know if anyone wants to try and include the entire document into the
documentation for Ruby, or if its even legal to do so.

 

[Michal Suchanek]

Well, they Ruby Core team does take patches.

It's not the same thing.

You can comment on the PHP documentation even if you don't know how to
make a patch and don't understand whatever format the docs are in.
Still people visiting the documentation site can read the comment.

It has its downsides, too. There are some meaningless comments or
multiple refinements of the same sample code.

Thanks

Michal

 

[Robert Klemme]

No. I think in ruby the code would be almost exactly the same--except
it's significantly harder to figure out in ruby because there is no
documentation about the format specifiers you can use with strftime()
and strptime(). Amazing, huh?

It's not very good to find but what about this?

http://ruby-doc.org/core-1.8.7/classes/Time.html#M000139

ruby and python are in the same state of evolution right now--both are
in the midst of a major version change. In both cases, the newer
versions won't have as many libraries available to them because most
libraries have not yet been rewritten to accommodate the latest version.
So the choice is: go with ruby 1.8.6 and have more libraries available
to you, or go with ruby 1.9.x to learn the latest greatest language
changes. I think most people probably have 1.8.6 and 1.9.x installed
side by side(in python it would be 2.6.x and 3.x). They probably use
1.8.6 for their serious programs, and then they play around with 1.9.x
to learn the new stuff.

I have both installed but use only 1.9 simply because it is
significantly faster and also because the new feature set seems better
to me. Since I am not using too many non standard libraries (and gems)
the library lag is not an issue for me.

Kind regards

robert

 

[Robert Klemme]

On Oct 6, 2009, at 1:16 AM, 7stud -- wrote:

No. I think in ruby the code would be almost exactly the same--except
it's significantly harder to figure out in ruby because there is no
documentation about the format specifiers you can use with strftime()
and strptime(). Amazing, huh?
Amazingly wrong, yeah:

Not at all:

1) $ri Date::strptime

--------------------------------------------------------- Date::strptime
Date::strptime(str='-4712-01-01', fmt='%F', sg=ITALY)
------------------------------------------------------------------------
Create a new Date object by parsing from a String according to a
specified format.

+str+ is a String holding a date representation. +fmt+ is the
format that the date is in. See date/format.rb for details on
supported formats.

The default +str+ is '-4712-01-01', and the default +fmt+ is '%F',
which means Year-Month-Day_of_Month. This gives Julian Day Number
day 0.

+sg+ specifies the Day of Calendar Reform.

An ArgumentError will be raised if +str+ cannot be parsed.
-----------------------------

Good luck finding and then digging through the **source code** of
format.rb to locate anything on the format specifiers.


2) $ri Date#strftime

---------------------------------------------------------- Date#strftime
strftime(fmt='%F')
------------------------------------------------------------------------
(no description...)



And from the official Standard Library Documentation for 'date':

1)
strptime(str='-4712-01-01', fmt='%F', sg=ITALY)
----------------------------------------

Create a new Date object by parsing from a String according to a
specified format.

str is a String holding a date representation. fmt is the format that
the date is in. See date/format.rb for details on supported formats.

The default str is ’-4712-01-01’, and the default fmt is ’%F’,which
means Year-Month-Day_of_Month. This gives Julian Day Number day 0.

sg specifies the Day of Calendar Reform.

An ArgumentError will be raised if str cannot be parsed.
=================


2)
strftime(fmt='%F')
--------------
[Source]

That last one is a real doozy--and quite typical of ruby Standard
Library documentation.

In this case I use the strftime(3) man page but windows users are at a
disadvantage here.

The man pages can be found on the web, though.

And while there are things that could use better documentation there
is no need to replicate documentation of ancient function which is
standardized in POSIX and wherever else.

That approach has its downsides as well: you won't be aware of %p in
Ruby's printf which is often helpful for logging and debugging.

Kind regards

robert

 

[Stefan Peters]

It's not the same thing.

You can comment on the PHP documentation even if you don't know how to
make a patch and don't understand whatever format the docs are in.
Still people visiting the documentation site can read the comment.

It has its downsides, too. There are some meaningless comments or
multiple refinements of the same sample code.

And lots of really bad/wrong/dangerous code (that is often c&p). I
dont think that comments are a good idea, but may be some kind of wiki
would be productive, because I also think, that the documentation
needs improvement.

Stefan

 

[Michal Suchanek]

James Edward Gray II wrote:

On Oct 6, 2009, at 1:16 AM, 7stud -- wrote:

No. =C2=A0I think in ruby the code would be almost exactly the same--= except
it's significantly harder to figure out in ruby because there is no
documentation about the format specifiers you can use with strftime()
and strptime(). =C2=A0Amazing, huh?

Amazingly wrong, yeah:

Not at all:

1) $ri Date::strptime

--------------------------------------------------------- Date::strptim= e
=C2=A0 =C2=A0Date::strptime(str=3D'-4712-01-01', fmt=3D'%F', sg=3DITALY= )
-----------------------------------------------------------------------= -
=C2=A0 =C2=A0Create a new Date object by parsing from a String accordin= g to a
=C2=A0 =C2=A0specified format.

=C2=A0 =C2=A0+str+ is a String holding a date representation. +fmt+ is = the
=C2=A0 =C2=A0format that the date is in. See date/format.rb for details= on
=C2=A0 =C2=A0supported formats.

=C2=A0 =C2=A0The default +str+ is '-4712-01-01', and the default +fmt+ = is '%F',
=C2=A0 =C2=A0which means Year-Month-Day_of_Month. This gives Julian Day= Number
=C2=A0 =C2=A0day 0.

=C2=A0 =C2=A0+sg+ specifies the Day of Calendar Reform.

=C2=A0 =C2=A0An ArgumentError will be raised if +str+ cannot be parsed.
-----------------------------

Good luck finding and then digging through the **source code** of
format.rb to locate anything on the format specifiers.


2) $ri Date#strftime

---------------------------------------------------------- Date#strftim= e
=C2=A0 =C2=A0strftime(fmt=3D'%F')
-----------------------------------------------------------------------= -
=C2=A0 =C2=A0(no description...)



And from the official Standard Library Documentation for 'date':

1)
strptime(str=3D'-4712-01-01', fmt=3D'%F', sg=3DITALY)
----------------------------------------

Create a new Date object by parsing from a String according to a
specified format.

str is a String holding a date representation. fmt is the format that
the date is in. See date/format.rb for details on supported formats.

The default str is =E2=80=99-4712-01-01=E2=80=99, and the default fmt i= s =E2=80=99%F=E2=80=99, which
means Year-Month-Day_of_Month. This gives Julian Day Number day 0.

sg specifies the Day of Calendar Reform.

An ArgumentError will be raised if str cannot be parsed.
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D


2)
strftime(fmt=3D'%F')
--------------
[Source]

That last one is a real doozy--and quite typical of ruby Standard
Library documentation.

In this case I use the strftime(3) man page but windows users are at a
disadvantage here.

The man pages can be found on the web, though.

And while there are things that could use better documentation there
is no need to replicate documentation of ancient function which is
standardized in POSIX and wherever else.

That approach has its downsides as well: you won't be aware of %p in Ruby= 's
printf which is often helpful for logging and debugging.

Ruby even has that?

Never needed it. It may be perhaps somewhat faster than string
interpolation and string addition but I prefer code readability over
speed, especially for debug prints. Logging may need any speed you can
get, though.

Also there is no need to resort to unix manpages there because
IO#printf refers to the method that has the format specifiers listed.

In general ruby documentation needs something that was introduced for
Oniguruma regex format: a format specification that is not a part of
method documentation but the relevant method/class descriptions refer
to it.

Thanks

Michal

 

[Michal Suchanek]

And lots of really bad/wrong/dangerous code (that is often c&p). I

Of course, the quality of the code posted as part of the comments
varies but if there is a common pitfall that is posted it is more
likely that somebody finds out and posts a correction before you look
than that you would not hit the same problem if you put together the
code yourself. It seems to me that in PHP language-specific pitfalls
are notoriously created by language misfeatures.

The weakness of PHP is it does not have irb so clarifying the
description for yourself is quite expensive.

Still a missing reference like the one with strftime format may not be
easy to find and could be added as a comment.

One of the other problems is that as any public forum you not only
need an infrastructure for collecting a and storing posts but also a
human moderator(s) to watch over the system.

dont think that comments are a good idea, but may be some kind of wiki
would be productive, because I also think, that the documentation
needs improvement.

The strength of the comments is that they are right below the description.

A separate wiki would likely die a quiet (or spammy) death.

I would guess it's even less likely to succeed than posting a doc patch.


Thanks

Michal

 

[7stud --]

And to think, this whole dilemma could have been avoided if you named
her Python.

lol.

 

[7stud --]

And lots of really bad/wrong/dangerous code (that is often c&p).

That's not the point of the comments in the php docs. The comments are
not supposed to serve as a model on how to write code. The comments
serve to point out the nuances and pitfalls of the various functions in
the docs. In that regard, they are invaluable. You can choose to do
what you want with the issues brought up in the comments--ignore it,
dismiss issues that are not important to your code, follow the advice in
other comments--and even post a better solution to an issue highlighted
in the comments.

In essence, php is self documenting--which is a heck of a lot better
than "not documented at all", which happens to be the state of affairs
with a lot of the ruby standard library. It's hard for me to believe
that a library is even admitted into the ruby standard library without
some minimum level of documentation.

In my opinion, if libraries aren't documented, then they really doesn't
even exist in any kind of useful sense, and therefore they should be
stricken from the language.

 

[Michael W. Ryder]

That's not the point of the comments in the php docs. The comments are
not supposed to serve as a model on how to write code. The comments
serve to point out the nuances and pitfalls of the various functions in
the docs. In that regard, they are invaluable. You can choose to do
what you want with the issues brought up in the comments--ignore it,
dismiss issues that are not important to your code, follow the advice in
other comments--and even post a better solution to an issue highlighted
in the comments.

In essence, php is self documenting--which is a heck of a lot better
than "not documented at all", which happens to be the state of affairs
with a lot of the ruby standard library. It's hard for me to believe
that a library is even admitted into the ruby standard library without
some minimum level of documentation.

In my opinion, if libraries aren't documented, then they really doesn't
even exist in any kind of useful sense, and therefore they should be
stricken from the language.

How much of the Ruby standard library is a port of the C standard
library? This has been documented since at least 1992 and is readily
available.

 

[Walton Hoops]

From: Michael W. Ryder [mailto:[email protected]]

How much of the Ruby standard library is a port of the C standard
library? This has been documented since at least 1992 and is readily
available.

This is at least the second person to say this, and I find it a little
scary. Just because C has these functions documented does NOT mean that
it is OK for Ruby not to. Just because C has a function named sprintf
does NOT mean that a Ruby/Python/PHP/any other langauges' sprintf will
work the same way.

Imagine this for a minute: there is a new browser in town. Everyone
loves it. So you decide to give it a shot. You find a really cool page
and you want to bookmark it. You look around, find the bookmark menu
and click add. It provides two empty textboxes with no labels. So you
look up adding a bookmark in the docs, and there is nothing there. So
you head for the mailing list and ask for help. Everyone says "No need
to document it, it's thoroughly documented in Firefox's documentation"
Is that good documentation pratice?

Bottom line: When I go to look up a function and I find no notation
whatsoever (not even "see 'x' function in c") it is not good
documentation, and it does not make for a good user expierience.

(This from a newbie who is loving the language, yet constantly,
hating the lack of documentation)

 

[Michael W. Ryder]

From: Michael W. Ryder [mailto:[email protected]]
How much of the Ruby standard library is a port of the C standard
library? This has been documented since at least 1992 and is readily
available.

This is at least the second person to say this, and I find it a little
scary. Just because C has these functions documented does NOT mean that
it is OK for Ruby not to.

I think it is more a matter of priorities. While you may find that the
lack of documentation of a function that is copied from C upsetting, I
would rather the developers use their limited time for more important,
to me at least, things. I prefer hard copy documentation and having a
copy of the C Standard Library on my desktop gives me this ability. I
have never been able to get the Ruby documentation to work, probably
because it was faster to grab the book.

Just because C has a function named sprintf

does NOT mean that a Ruby/Python/PHP/any other langauges' sprintf will
work the same way.

I would expect anyone making a new version of sprintf to rename the
function to forestall the inevitable tarring and feathering. It would
be like changing the meaning of black to mean light purple. People
expect words, and function names are words, to not change.

Imagine this for a minute: there is a new browser in town. Everyone
loves it. So you decide to give it a shot. You find a really cool page
and you want to bookmark it. You look around, find the bookmark menu
and click add. It provides two empty textboxes with no labels. So you
look up adding a bookmark in the docs, and there is nothing there. So
you head for the mailing list and ask for help. Everyone says "No need
to document it, it's thoroughly documented in Firefox's documentation"
Is that good documentation pratice?

I am not saying that it is good practice but there is some logic in
this. If your new browser used Firefox as a base if a change was made
to Firefox the change may percolate up into the new browser. So there
will be changes made to the documentation. Which do you think will
happen first, the well supported Firefox browser, or the small team
using the Firefox code?

Bottom line: When I go to look up a function and I find no notation
whatsoever (not even "see 'x' function in c") it is not good
documentation, and it does not make for a good user expierience.

The documentation for the language does not bother me anywhere near as
much as the changes breaking old code and no way to find out what is
broken without experience. Different documentation faults.

 

[David Masover]

As of sometime recently, there were reports of some Rails stuff not working
on it, which might be a good reason.

Which Rails stuff?
Especially considering Rails officially supports 1.9, I thought.

 

[Seebs]

Which Rails stuff?
Especially considering Rails officially supports 1.9, I thought.

Don't remember now. Ahh!

https://rails.lighthouseapp.com/pro...kets/3144-undefined-method-for-string-ror-234

There's a use of a ^ b broken by the change from a being the
integer char value to a string.

May be specific to 2.3.4.

-s

 

[David Masover]

Don't remember now. Ahh!

https://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets/3144-un
defined-method-for-string-ror-234

Ah, I see. And it's resolved.

So, probably fewer bugs on 1.8, probably some undiscovered 1.9-related bugs.
Wouldn't stop me from using 1.9 -- it's stable enough that I'm as likely to
find a 1.9-specific bug as a general bug in Rails.