Proofreading of YARD docs needed

[alexdowad]

The newly written YARD documentation needs a second person to proofread. Check that the docs are:

• Accurate (if they don't match the actual method behavior, either the docs or the method itself could be buggy)
• Reasonably complete, without belaboring details too much (what users need to know should be there)
• Reasonably easy to understand

This could be done either by reviewing the output of YARD, or by reading the embedded docs directly in the source code.

• Hash
• Set
• Vector
• SortedSet
• List
• Deque

[xaviershay]

Link to online reading: http://www.rubydoc.info/github/hamstergem/hamster/master/Hamster

I'm having a go at this.

[xaviershay]

Why are Hash#put and Hash#store not aliases of one another? Seems weird to have both, but maybe that's backwards compat?

[alexdowad]

@xaviershay, you're right, there is no reason why Hash#put and Hash#store should not be aliases. To provide some background, #store was added to make the interface of Hamster::Hash match that of Ruby's built-in Hash. #put is common to all the Hamster collections.

Any chances of sending a PR for this one?

[alexdowad]

I just pushed a fix for the YARD docs for Hamster.replicate, you may want to pull before continuing your review.

[xaviershay]

thanks for background. Could send PR, but if store is supposed to match Ruby interface then maybe I'll just document it as such. Hoping to get a once over of all the Hash docs done today - will send that up and if you like it I can tackle the rest.

[xaviershay]

Will probably make a different issue for this, but given we are making performance claims ("At the same time, they remain CPU and memory-efficient by sharing between copies.") would probably be good to include expected operation cost in the YARD docs (O(1), O(n), etc). This is a thing I like about the redis docs.

[alexdowad]

"Include expected operation cost..."

Hmm, sounds like a good idea.

[alexdowad]

@xaviershay, thanks for proofreading ALL the docs for the entire project! It is impressive to see how much better you made them!