Where do you keep the documentation of a field?

rubyonrails-talk
1

We have a model NumberPool with a column reserve_size

In the UI we show documentation to the user and this documentation is coming from config/locales/en.yml where we’ve described what this reserve_size is for and what does it mean.

But it is not in the model. When developing specs you don’t know what reserve_size. When using the NumberPool you don’t know what the reserve_size is. You have to remember to go and check in en.yml

I am wondering how do you guys keep the documentation of the field where the field is? Do you think it could stay with the class itself or in some other way to make it easier to work with classes that you don’t know and in the same time not to repeat the same documentation text in the class and in en.yml

1 Like
2

So for short docs. e.g period. And the docs is “Value is number of month”

I usually creates a comment along when creating the field.

add_column :reports, :period, :integer, comment: "Value is number of month".

I use annotate rails gem. And it will show the comment nicely in the model.

For longer docs, Id like to know too.

1 Like
3

Thanks @yana

annotate gem is a good idea. Now what if annotate could take the value from the en.yml so that developers and users see the same documentation of a field :smiley: