I'm trying to learn as much as I can about AREL. But I'm not sure what to look at.
I found some documentation on rubydoc, but it doesn't seem very good in terms of showing what are the "public API"/accessible things I can do. For example, I could not find any information on the "includes" method.
So, how exactly to learn most of what AREL has to offer? (i.e. without delving into the source code)
I think that this will be useful :
https://github.com/brynary/arel
And an interesting asciicast :
http://asciicasts.com/episodes/215-advanced-queries-in-rails-3
Complete documentation is here: http://rubydoc.info/github/rails/arel/master/Arel Look in the modules for specific methods.
I wrote an article about Arel a few weeks ago (The definitive guide to Arel, the SQL manager for Ruby). It walks through the whole library and explains how things work internally and how you can use it from your own application.
I got tired of reading tests and code, in the arel tree, so I put some slides together. They cover v2.x, I haven't even looked at v3 yet.
Yeah, I'm having a real hard time finding doc too. The Arel test suite might be of some use:
https://github.com/rails/arel/blob/master/test/test_select_manager.rb