Also, when you see those long dashed lines with the class/module and possibly a method name on the right, that tells you what to type into ri. I literally typed:
ri Time#strftime
James Edward Gray II
On Oct 6, 2009, at 8:14 AM, Glen Holcomb wrote:
On Tue, Oct 6, 2009 at 6:54 AM, James Edward Gray II > <james@graysoftinc.com>wrote:
----------------------------------------------------------Time#strftime
If anyone is curious where the information James provided can be found:
With the above approach one might benefit by starting with:
ri strftime
Then looking at "all" the strftime methods.
On Tue, Oct 6, 2009 at 12:33 PM, 7stud -- <bbxx789_05ss@yahoo.com> wrote:
James Edward Gray II wrote:
> 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.--
Posted via http://www.ruby-forum.com/\.
--
"Hey brother Christian with your high and mighty errand, Your actions speak
so loud, I can’t hear a word you’re saying."
-Greg Graffin (Bad Religion)
You've been shown the format option from the documentation. I'm not sure how much more proof you require.
I agree that they could be copied to the Date methods and any specific format options for those methods could be added. But to say there's no documentation was just plain wrong.
You've obviously gone into the source to find them once, to bad you didn't create a documentation patch while you were there.
James Edward Gray II
On Oct 6, 2009, at 1:33 PM, 7stud -- wrote:
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.
Thanks
Michal
2009/10/6 7stud -- <bbxx789_05ss@yahoo.com>:
James Edward Gray II wrote:
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.
7stud -- wrote:
James Edward Gray II 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.
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.
On Oct 6, 2009, at 1:16 AM, 7stud -- wrote:
Don't remember now. Ahh!
There's a use of a[i] ^ b[i] broken by the change from a[i] being the
integer char value to a string.
May be specific to 2.3.4.
-s
On 2009-10-07, David Masover <ninja@slaphack.com> wrote:
On Tuesday 06 October 2009 01:00:05 pm Seebs wrote:
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.
--
Copyright 2009, all wrongs reversed. Peter Seebach / usenet-nospam@seebs.net
| Seebs.Net <-- lawsuits, religion, and funny pictures
Fair game (Scientology) - Wikipedia <-- get educated!
Hi --
On Tue, 6 Oct 2009, Adam Bilbrough wrote:
flebber wrote:
On Oct 6, 7:49???pm, Adam Bilbrough <adambilbro...@rocketmail.com> >> wrote:
To: "ruby-talk ML" <ruby-t...@ruby-lang.org>
At the time I had no knowledge and tossed up between Ruby and Python,
this be significantly easier in Ruby.
??? ??? ??? ???userIn = raw_input("Type Date dd/mm/yy: ")
??? ??? ??? ??? ??? ???print "Try again! dd/mm/yy\n"
??? ???Fname = "data.dat"
??? ???newFname = d2 + Fname
??? ???return newFname
print ObtainDate()-- Kind Regards,
Rajinder Yadavhttp://DevMentor.org
Do Good ~ Share FreelySo If I use version 1.8.6 and later want to update my project to the
1.9 series would this be a hard conversion?For Ruby, no. Tt has no specific indentations to follow (within reason)
and the only things that have changed as far as I know (been a while
since I read the release docs) 1.9.1 adds some new functionality to Ruby
but doesn't change the syntax (like Python 2 - 3 did).
With my program I was working on, I was using 1.9.1 (on my old linux
distro) and also running it on my Mac (1.8.7), so as far as the scope of
my program was concerned, the versions were universally capable of
running on either system with zero changes.
The syntax has actually changed in certain respects. See:
http://dablog.rubypal.com/2009/1/14/10-things-to-be-aware-of-in-moving-to-ruby-1-9
and the sequel post (there's a link).
David
--
David A. Black, Director
Ruby Power and Light, LLC (http://www.rubypal.com)
Ruby/Rails training, consulting, mentoring, code review
Book: The Well-Grounded Rubyist (http://www.manning.com/black2\)
James Edward Gray II wrote:
That last one is a real doozy--and quite typical of ruby Standard
Library documentation.You've been shown the format option from the documentation. I'm not
sure how much more proof you require.
I already knew the format specifiers were described in the Time class.
The question is whether someone new to ruby could figure out how to
format Date objects. I think not. The reason: ruby has poor
documentation.
You've obviously gone into the source to find them once, to bad you
didn't create a documentation patch while you were there.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.
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
On 10/06/2009 08:59 PM, Michal Suchanek wrote:
2009/10/6 7stud -- <bbxx789_05ss@yahoo.com>:
James Edward Gray II wrote:
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.
--
remember.guy do |as, often| as.you_can - without end
http://blog.rubybestpractices.com/
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.
On Wednesday 07 October 2009 06:45:15 pm Seebs wrote:
On 2009-10-07, David Masover <ninja@slaphack.com> wrote:
> On Tuesday 06 October 2009 01:00:05 pm Seebs wrote:
>> 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.Don't remember now. Ahh!
#3144 undefined method `^' for String - RoR 2.3.4 - Ruby on Rails - rails
defined-method-for-string-ror-234
Well, they Ruby Core team does take patches.
James Edward Gray II
On Oct 6, 2009, at 1:59 PM, 7stud -- wrote:
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.
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
2009/10/7 Robert Klemme <shortcutter@googlemail.com>:
On 10/06/2009 08:59 PM, Michal Suchanek wrote:
2009/10/6 7stud -- <bbxx789_05ss@yahoo.com>:
James Edward Gray II wrote:
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.
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
2009/10/6 James Edward Gray II <james@graysoftinc.com>:
On Oct 6, 2009, at 1:59 PM, 7stud -- wrote:
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.
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
On 6 Okt., 23:15, Michal Suchanek <hramr...@centrum.cz> wrote:
2009/10/6 James Edward Gray II <ja...@graysoftinc.com>:
> On Oct 6, 2009, at 1:59 PM, 7stud -- wrote:
>> 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.
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.
>> 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.
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
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
2009/10/7 Stefan Peters <stefan@heart-core.net>:
On 6 Okt., 23:15, Michal Suchanek <hramr...@centrum.cz> wrote:
2009/10/6 James Edward Gray II <ja...@graysoftinc.com>:
> On Oct 6, 2009, at 1:59 PM, 7stud -- wrote:
Stefan Peters wrote:
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).
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.
On 6 Okt., 23:15, Michal Suchanek <hramr...@centrum.cz> wrote:
--
Posted via http://www.ruby-forum.com/\.
7stud -- wrote:
Stefan Peters wrote:
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).
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.
On 6 Okt., 23:15, Michal Suchanek <hramr...@centrum.cz> wrote:
From: Michael W. Ryder [mailto:_mwryder@worldnet.att.net]
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)
Walton Hoops wrote:
From: Michael W. Ryder [mailto:_mwryder@worldnet.att.net]
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.
(This from a newbie who is loving the language, yet constantly,
hating the lack of documentation)