Great article. However, you should be using YARD. Along with: https://github.com/lsegal/yard-spec-plugin

It's really common, actually. A symbol can actually have spaces in it:

:"Some Text" is a perfectly valid symbol.

ruby-1.9.2-p136 :001 > h = {:"Some Text" => 123} => {:"Some Text"=>123} ruby-1.9.2-p136 :002 > h[ "Some Text".to_sym ] => 123

You can do it, but is it a good idea? What it implies to me is that at some point in your program, you're constructing symbols from arbitrary strings which aren't known ahead of time. This sounds like a recipe for disaster given that symbols aren't garbage collected.