AwesomeAnnotate

AwesomeAnnotate adds generated schema and route comments to Rails applications.

This gem is intended as a small replacement-style tool for the basic features of the original annotate gem:

  • annotate model files with Active Record schema information
  • annotate config/routes.rb with the application's route table
  • replace previous AwesomeAnnotate blocks instead of appending duplicates
  • remove generated AwesomeAnnotate blocks

Requirements

  • Ruby 3.0 or later, below 4.0
  • Active Record 6.1 or later, below 8.0
  • Rails application layout with config/environment.rb

Development currently uses the Ruby version in .ruby-version.

Installation

Add this line to your Rails application's Gemfile:

gem 'awesome_annotate'

Then run:

bundle install

If you are using this repository directly before publishing the gem, use a Git source instead:

gem 'awesome_annotate', git: 'https://github.com/wisdom-plus/awesome_annotate'

Usage

Run commands from the root directory of a Rails application.

Available commands:

bundle exec awesome_annotate model user
bundle exec awesome_annotate models
bundle exec awesome_annotate models user article admin/user
bundle exec awesome_annotate routes
bundle exec awesome_annotate all
bundle exec awesome_annotate remove model user
bundle exec awesome_annotate remove models
bundle exec awesome_annotate remove routes
bundle exec awesome_annotate remove all

Annotate a model:

bundle exec awesome_annotate model user

Annotate all models:

bundle exec awesome_annotate models

Annotate specific models:

bundle exec awesome_annotate models user article admin/user

Annotate all models and routes:

bundle exec awesome_annotate all

Remove generated annotations:

bundle exec awesome_annotate remove model user
bundle exec awesome_annotate remove models
bundle exec awesome_annotate remove routes
bundle exec awesome_annotate remove all

This loads config/environment.rb, resolves User, reads its Active Record columns, and writes a schema block before the class definition in app/models/user.rb:

# == AwesomeAnnotate: columns
# == Schema Information
#
# Table name: users
#
#  id         :integer  not null, primary key
#  name       :string
#  email      :string   not null, default("")
#  created_at :datetime not null
#  updated_at :datetime not null
#
# Indexes
#
#  (email)       UNIQUE, index_users_on_email
#  (name,email)  index_users_on_name_and_email
#
# == /AwesomeAnnotate: columns
class User < ApplicationRecord
end

Annotate routes:

bundle exec awesome_annotate routes

This writes a generated route block before Rails.application.routes.draw do in config/routes.rb:

# == AwesomeAnnotate: routes
# Prefix Verb URI Pattern Controller#Action
# users GET /users(.:format) users#index
# == /AwesomeAnnotate: routes
Rails.application.routes.draw do
end

Print the gem version:

bundle exec awesome_annotate --version

Short aliases are also available:

bundle exec awesome_annotate -m user
bundle exec awesome_annotate -r
bundle exec awesome_annotate -v

Generated Blocks

AwesomeAnnotate wraps generated comments with start and end markers:

# == AwesomeAnnotate: columns
# ...
# == /AwesomeAnnotate: columns

When the command is run again, the existing block with the same marker is replaced. This prevents duplicate annotations from being appended on repeated runs.

Current Limitations

  • Only model schema blocks and routes are supported.
  • Model annotations include column type, nullability, primary key, and default values, plus basic index information.
  • Model annotation currently targets files under app/models.
  • Model class detection expects a simple class declaration such as class User < ApplicationRecord.
  • Existing comments generated by other annotate tools are not migrated or removed automatically.
  • Ruby 4 is not currently supported.

Development

Install dependencies:

bundle install

Run the test suite:

bundle exec rspec

Run RuboCop:

bundle exec rubocop

Build the gem locally:

bundle exec rake build

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/wisdom-plus/awesome_annotate.

License

The gem is available as open source under the terms of the MIT License.