If you just want to have column descriptions in your model file, annotate_models should suite you well. Annotator will help you if you want to also keep your own comments about these columns.
Ever wondered what the heck is that column used for?
In your Gemfile:
Then in app directory:
Let's say you have a Foo model:
# My Foo model, it's awesome class Foo < ActiveRecord::Base
Make sure your working tree is clean (it's suggested tu put annotations in separate commits so you can easily review changes done by annotator before commiting and you can always easily revert them all) and run:
Then it should become something like:
# My Foo model, it's awesome # Attributes: # * id [integer, primary, not null, limit=4] - primary key # * body [text] - TODO: document me # * created_at [datetime] - creation time # * title [string] - TODO: document me class Foo < ActiveRecord::Base
Now you can edit these TODOs and run it again, nothing happens. But when you add new column and run it again:
# My Foo model, it's awesome # Attributes: # * id [integer, primary, not null, limit=4] - primary key # * body [text] - there we store foo complicated body # * created_at [datetime] - creation time # * some_number [integer, limit=4] - TODO: document me # * title [string] class Foo < ActiveRecord::Base
Of course similar thing happens when you remove column or change it's type.
Some actually useful information
it recognizes it's own block by “Attributes:” and then punctation list
if you don't want it to update anything, put “Attributes(nodoc):” instead
for some fields like title above you can just skip description including dash sometimes name is just obvious enough
multiline comments are ok
generating initial descriptions it understands things like
belongs_to association columns
you can run it without rails (if you use sinatra for example), just add something like this to your Rakefile
task :annotate do require 'annotator' Annotator.run(File.join(Dir.pwd, "lib", "models")) end
Contributions are very much welcome.
since name does not have “model” in it, we could possibly use “rake routes” to annotate controller actions, not sure if it's worth it
Kacper Cieśla @ Tech-Angels - www.tech-angels.com
Annotator is released under the MIT license.