@ravage84 docs in a doc block show up in the api, so inline docs are only found by reading the source. As such I much prefer docs in doc blocks, and code that's self-documenting =)