7stud -- wrote:
> Stefan Peters wrote:
>> On 6 Okt., 23:15, Michal Suchanek <hramr... / centrum.cz> 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.