Add Yardoc for documentation

see http://rubydoc.info/docs/yard/file/docs/GettingStarted.md
Add extra files to the docs
Document STI classes
Add yard notice to the README
Move some docs back to the doc folder but in a subfolder
Comment the document model
More comments on edition

also reorder methods
Commented and reordering edition class methods
remove old readme, this is now generated with yard
Add link to generated docs on rdoc.info
Rename /doc/ to /docs/ and ignore yardoc output

Yard generates docs in the /doc/ subdirectory. We don't want to commit
these to git.

However, I suspect that rdoc.info relies on the generated docs going to
a certain directory (although I haven't tested this). To ensure that
rdoc.info will continue to automatically work, I've renamed /doc/ to
/docs/ and added .gitignore for /doc/
Fix yardops after doc directory renamed
Merge pull request #598 from alphagov/yardoc

Start to use YARD :thumbsup: