doc with yard: examples

[noraj]

As there is no documentation outside the README, I wanted to start introducing library documentation with yard. I showcased a few simple examples in this PR.

Yard is automatically used for https://www.rubydoc.info/.

Here is an example for what it can looks like on one of my projects:

https://rubydoc.info/gems/unisec/Unisec%2FSurrogates%2Ehigh_surrogate

https://rubydoc.info/gems/unisec/Unisec%2FSurrogates:initialize

For example here on property_values_for, @return [Array<String>|nil] indicates it can either return an Array of string or nil. It's nice to be able to read it from the doc rather than having to read all the source code to figures it out. Indeed, one could expect that when a property don't have values it returns an empty Array and not nil. Not all the code is explicit so it may be nice to explain it at least for complex methods or one with not trivial behavior.

Let me know what you think, if the style is ok, should I continue to PR some doc, etc?

[CLAassistant]

All committers have signed the CLA.

[camertron]

Hey @noraj, thanks for this, I'd love to get everything annotated with YARD 😄 I'm happy to merge once the CLA has been signed 👍

[noraj]

I signed it earlier, retried just now, I click the refresh link but the CLA app seems broken, it's never good on the issue.