annotate_models

To remove schema annotations from all model files, tests, fixtures, factories, and serializers, use the --delete flag.

annotate --delete

To ensure your annotations stay up-to-date whenever you run migrations, you can set up automatic annotation.

Option 1: Use the generator

rails g annotate:install

This creates a configuration file in lib/tasks/auto_annotate_models.rake and sets up the automation.

Option 2: Manual Rakefile update Add the following line to your Rakefile:

Annotate.load_tasks

Note: By default, this only runs in development mode. To run a migration without triggering annotation, use the environment variable:

ANNOTATE_SKIP_ON_DB_MIGRATE=1 rake db:migrate

In a Rails application, use the annotate command to add schema information as comments to your files. By default, it targets ActiveRecord models, tests, fixtures, and factories.

Annotate everything:

annotate

Annotate only models, tests, and factories (excluding fixtures):

annotate --models --exclude fixtures

Annotate only models:

annotate --models

The annotate tool documents foreign key relationships in the schema. It follows the format: fk_rails_... (ON DELETE => on_delete_value ON UPDATE => on_update_value), followed by the mapping of the local column to the referenced table and column.

### Foreign Keys

* `fk_rails_...` (_ON DELETE => on_delete_value ON UPDATE => on_update_value_):
    * **`foreign_thing_id => foreign_things.id`**

The annotate tool provides schema information for database tables, including column names, data types, and attributes (such as not null or primary key).

Table name: `users`

### Columns

Name                    | Type               | Attributes
----------------------- | ------------------ | ---------------------------
**`id`**                | `integer`          | `not null, primary key`
**`foreign_thing_id`**  | `integer`          | `not null`

The annotate tool can generate a Route Map that summarizes your application's routing configuration. This map displays the Prefix, HTTP Verb, URI Pattern, and the corresponding Controller#Action for each route.

Prefix    | Verb       | URI Pattern     | Controller#Action    
--------- | ---------- | --------------- | --------------------
myaction1 | GET        | /url1(.:format) | mycontroller1#action
myaction2 | POST       | /url2(.:format) | mycontroller2#action
myaction3 | DELETE-GET | /url3(.:format) | mycontroller3#action

You can install the annotate gem via Gemfile or directly into your environment.

Using Gemfile (Recommended for Rails):

group :development do
  gem 'annotate'
end

Using Gemfile from GitHub:

group :development do
  gem 'annotate', git: 'https://github.com/ctran/annotate_models.git'
end

Direct Installation:

gem install annotate

Annotate produces MultiMarkdown using syntax extensions for tables. To correctly render these in YARD documentation, configure your .yardopts file to use markdown with the kramdown provider.

--markup markdown
--markup-provider kramdown

To add the output of rake routes as a comment to your routes.rb file, use the --routes flag.

annotate --routes

To remove existing routes annotations:

annotate --routes --delete

If you want to prevent annotate from touching a specific file, add the following comment anywhere in that file:

# -*- SkipSchemaAnnotations

If you want to use the MultiMarkdown format produced by Annotate (which uses table syntax extensions), add kramdown to your Gemfile.

gem 'kramdown', groups => [:development], require => false

Running rails g annotate:install generates a configuration file (a .rake file) that allows you to set default options.

Key configuration settings include:

• skip_on_db_migrate: Set to 'true' to permanently disable automatic annotation during db:migrate.
• Output format and placement (top or bottom of file).
• Target artifacts (models, tests, etc.).

The generated file is located at lib/tasks/auto_annotate_models.rake.