How to best document value classes with yard?

[ms-ati]

I suggest that there should be a documented best practice for documenting value classes with yard.

Requirements:

• Works on rubydoc.info for docs
• Works in Rubymine for completion
• Allows documenting the type(s) of each field

I've put a gist together showing how it currently works. As you can see, Example3 works about 75%, which I think is the best we can do at the moment.

So that leads me to a documentation proposal. What do you think of this:

---

How to Document a Value class using YARD

Current best practice for writing YARD documentation for value classes created with this gem can be best summed up as "make them look like Structs for YARD":

1. Use the inheritance syntax (eg class A < Value.new(...)) rather than assigning to a constant
2. Document each field using YARD tag @attr_reader (docs)

Example

# What is a person?
#
# @attr_reader [String]        name     Full name
# @attr_reader [Fixnum]        age      Age in years
# @attr_reader [Array<Person>] friends  List of friends
class Person < Value.new(:name, :age, :friends); end

Still TODO

• tell YARD about generated constructor
• tell YARD about generated class methods: .with
• tell YARD about the generated instance methods: #==, #eql?, #values, #inspect, #with, #to_h, #to_a