Ruby documentation

[shorowit]

Use consistent documentation of ruby methods, classes, etc. YARD is popular, but RDoc comes with ruby. We're not looking to host documentation for our code, just ensure the code is documented well.

Could use rdoc -C to ensure everything is properly documented in a CI test: "X.XX% documented".

[joseph-robertson]

Writing documentation for rdoc:

• https://ruby.github.io/rdoc/#label-Writing+Documentation
• https://rubydoc.info/stdlib/rdoc/2.1.0/RDoc/RDoc
• https://devhints.io/rdoc

[joseph-robertson]

Another idea is to use rubocop to enforce documentation comments. For example, add 'Style/DocumentationMethod' to tasks.rb, and you see C: 11: 3: Style/DocumentationMethod: Missing method documentation comment. when running update_measures.

[shorowit]

Cool! I wasn't aware of that. Looks like we'd also want to use 'Style/Documentation'.

[joseph-robertson]

Writing documentation using yard:

• https://rubydoc.info/gems/yard/file/docs/GettingStarted.md
• https://rubydoc.info/gems/yard/0.9.36/YARD
• https://rubydoc.tenderapp.com/kb/getting-started-with-rubydocinfo/setting-up-a-yardopts-file