I spent all my time trying to figure out ‘how to do things’. Once I figured it out, it was great…and elegant…but what’s the point, there was too much magic at times to figure out what was happening.

A language can be pretty, but it’s the libraries that make it useful and practical.

I learned an important lesson: judge technology by documentation, not by the fact it is sexy or elegant.

However, the API is not the language. Not at all. You don’t have to use any of those 108 libraries to use Ruby.

If you understand network programming, the constants in the socket library should be self-evident. See where I am going here?

Looks potentially interesting and could fit really nicely into this challenge

Here’s what I discovered this weekend
- In the standard library, in IO/wait. From what I’m able to tell, the first method,”nread”, doesn’t even exist for the Windows implementation of the interpreter. I can see the other methods from that class, but this one literally is not there. No mention of this in the API.

- The second method, “ready”, does exist but is WRONGLY implemented — I dont even think its a bug. It ALWAYS returns false, no matter what, like the implementer just got lazy. I just can’t understand that…either implement it, or at least put a note in the API, or at least throw an error when its called that says “WARNING: not implemented on your OS!”. Took me hours to figure this out. Tell me, Matz, how exactly does this fit in with the Principle of Least Surprise?

- The doc for the primary IO class has no references to IO/wait or Open3, both of which are also part of the standard library and are essentially extensions of the primary IO class which are very valuable.

- The doc for IO.select just contains a link to the doc for Kernel.select. The doc for Kernel.select just contains a link to the doc for Kernel.select. That’s right, it has a link to itself, lmao.

- All links in the API seem to be done somewhat mechanically, rather than being done by humans. So the definition for IO.read_nonblock says it works by “using the read(2) system call”. The “read” part of read(2) is a link to IO.read, which is a blocking read that takes N bytes. So if you interpret the documentation literally, it defines IO.read_nonblock as a blocking read of 2 bytes. If you’re someone who happens to know UNIX system calls, you might recognize the typo. But this kind of bullshit is rampant throughout the documentation, and I feel bad for the confused kid who’s trying to pick up his first programming language, ruby, and is completely lost.

And if I want to edit the docs myself, the only thing I can find is this BS about how I have to access their subversion repository and modify the source code. To fix a typo? A simple “corrections” submission form would be too difficult because…?

I’m only angry because I genuinely LIKE the language. The OO features, the basic data structures, even little things like ruby’s equivalent of a Switch statement are very expressive, well-abstracted, and beautiful. But once I start dealing with anything system-related I feel like I’m using poorly-documented C functions. The language is bloody 15 years old and they still can’t be bothered to make it accessible. Or maybe its just my fault and I’m the idiot for not learning Japanese!

>_<
Waaaaaaaaaaaaaaaaaaa