How to document class_property?

Help & Support
1

For configuration purposes, I use a Config module containing a number of properties, such as :

class_property format : String = "%.2f"

and if I want to document this property by writing

# Returns or set format (Default "%.2f")
class_property format : String = "%.2f"

crystal docs returns

def self.format : String#    
Returns or set format (Default "%.2f")

def self.format=(format : String)#
Returns or set format (Default "%.2f")

which doesn’t seem very appropriate.

I haven’t found any solution other than replacing class_property with class_getter and class_setter, but that seems a bit cumbersome.

Any other solution ?

2

No unfortunately the property based macros will define the same message on both the getter and setter. If you want them to be different, would have to split them as you already noted. I’ve ran into this myself in the past :/.

Now that we have the @caller macro, is possible we could do something to tell it this message goes on the getter while this message goes on the setter. Tho probably would be quite complex and debatable if it’s worth the effort.

3

Yeah if you want separate doc comments, just use separate getter and setter. This is most straightforward and semantically entirely equivalent.

property is a short cut when you want just a quick and simple way to define an ivar an accessors for it.
If you want to add extended documentation, this short cut doesn’t work.

1 Like