gem annotate の README を翻訳しました

# 概要
gem [annotate](https://github.com/ctran/annotate_models) の [README](https://github.com/ctran/annotate_models/blob/develop/README.md) を翻訳しました。

- 翻訳について
    - 翻訳サービス [Deepl](https://www.deepl.com/translator) と [Goole翻訳](https://translate.google.co.jp/) の訳文を参考にしている箇所があります。
    - 翻訳対象の[コミットハッシュ](https://github.com/ctran/annotate_models/commit/2182f90b419a2b4b43068ff4c78f13a10a9db9c4)
    - 非公式の翻訳です。
    - 訳文がおかしい箇所があったら指摘をもらえると幸いです。

- ライセンスについて
    - [annotate のライセンス](https://github.com/ctran/annotate_models/blob/develop/LICENSE.txt)と同様に、BSD ライセンスに従います。

# オプションの目次

- [`--additional-file-patterns`](#--additional-file-patterns)
- [`-d, --delete`](#-d---delete)
- [`-p [before|top|after|bottom], --position`](#-p-beforetopafterbottom---position)
- [`--pc, --position-in-class [before|top|after|bottom]`](#--pc---position-in-class-beforetopafterbottom)
- [`--pf, --position-in-factory [before|top|after|bottom]`](#--pf---position-in-factory-beforetopafterbottom)
- [`--px, --position-in-fixture [before|top|after|bottom]`](#--px---position-in-fixture-beforetopafterbottom)
- [`--pt, --position-in-test [before|top|after|bottom]`](#--pt---position-in-test-beforetopafterbottom)
- [`--pr, --position-in-routes [before|top|after|bottom]`](#--pr---position-in-routes-beforetopafterbottom)
- [`--ps, --position-in-serializer [before|top|after|bottom]`](#--ps---position-in-serializer-beforetopafterbottom)
- [`--w, --wrapper STR`](#--w---wrapper-str)
- [`--wo, --wrapper-open STR`](#--wo---wrapper-open-str)
- [`--wc, --wrapper-close STR`](#--wc---wrapper-close-str)
- [`-r, --routes`](#-r---routes)
- [`--models`](#--models)
- [`-a, --active-admin`](#-a---active-admin)
- [`-v, --version`](#-v---version)
- [`-m, --show-migration`](#-m---show-migration)
- [`-k, --show-foreign-keys`](#-k---show-foreign-keys)
- [`--ck, --complete-foreign-keys`](#--ck---complete-foreign-keys)
- [`-i, --show-indexes`](#-i---show-indexes)
- [`-s, --simple-indexes`](#-s---simple-indexes)
- [`--model-dir dir`](#--model-dir-dir)
- [`--root-dir dir`](#--root-dir-dir)
- [`--ignore-model-subdirects`](#--ignore-model-subdirects)
- [`--sort`](#--sort)
- [`--classified-sort`](#--classified-sort)
- [`-R, --require path`](#-r---require-path)
- [`-e [tests,fixtures,factories,serializers], --exclude`](#-e-testsfixturesfactoriesserializers---exclude)
- [`-f [bare|rdoc|yard|markdown], --format`](#-f-barerdocyardmarkdown---format)
- [`--force`](#--force)
- [`--frozen`](#--frozen)
- [`--timestamp`](#--timestamp)
- [`--trace`](#--trace)
- [`-I, --ignore-columns REGEX`](#-i---ignore-columns-regex)
- [`--ignore-routes REGEX`](#--ignore-routes-regex)
- [`--hide-limit-column-types VALUES`](#--hide-limit-column-types-values)
- [`--hide-default-column-types VALUES`](#--hide-default-column-types-values)
- [`--ignore-unknown-models`](#--ignore-unknown-models)
- [`--with-comment`](#--with-comment)
- [オプション: `additional_file_patterns`](#%E3%82%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3-additional_file_patterns)

## Annotate (aka AnnotateModels)

下記のファイルの上部あるいは下部に現在の DB スキーマを要約したコメントを追加します。

- ActiveRecord models
- Fixture files
- Tests and Specs
- Object Daddy exemplars
- Machinist blueprints
- Fabrication fabricators
- Thoughtbot's factory_bot factories, i.e. the `(spec|test)/factories/<model>_factory.rb` files
- `routes.rb` file (for Rails projects)

スキーマコメントは下記のように記載されます。

```ruby
# == Schema Info
#
# Table name: line_items
#
#  id                  :integer(11)    not null, primary key
#  quantity            :integer(11)    not null
#  product_id          :integer(11)    not null
#  unit_price          :float
#  order_id            :integer(11)
#

class LineItem < ActiveRecord::Base
  belongs_to :product
  . . .
```

また、`SpatialAdapter` , `PostgisAdapter` , `PostGISAdapter` のいずれかを使用したときは、`geom` タイプや `srid` タイプのような幾何学的なカラムにも注釈をつけます。

```ruby
# == Schema Info
#
# Table name: trips
#
#  local           :geometry        point, 4326
#  path            :geometry        line_string, 4326
```

また、`-r` オプションを渡すと、`rake routes` の出力を `routes.rb` にコメントとして追加します。

## 3.Xにアップグレードするとモデルへの注釈が動作しない？

バージョン 2.7.X では、引数が何も渡されない場合は、gem annotate はデフォルトでモデルに注釈を追加していました。
デフォルトでは、gem annotate は routes とモデルが一緒に注釈を追加されることを許可していません。
[#647 で変更が追加](https://github.com/ctran/annotate_models/pull/647)されました。
詳細は[こちら](https://github.com/ctran/annotate_models/issues/663)でご覧ください。


この問題を修正する方法はいくつかあります。

- CLI を使用している場合は、`--models` を使用してモデルフラグを明示的に渡してください。

あるいは

a) `rails g annotate:install` を実行し、デフォルト設定が `models` オプション `'true'` になるように上書きします。

b) `lib/tasks/auto_annotate_models.rake` において `models` のキーと値を追加します。

```ruby
    Annotate.set_defaults(
      ...
      'models'                      => 'true',
      ...
```

## インストール

rubygems.org から 追加

```ruby
group :development do
  gem 'annotate'
end
```

Github から 追加

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

rubygems.org からインストール

    gem install annotate

Github のチェックアウトからインストール

    git clone https://github.com/ctran/annotate_models.git annotate_models
    cd annotate_models
    rake build
    gem install pkg/annotate-*.gem

## 利用方法

もし Gemfile 経由でインストールをしているなら、`bundle exec` を下記コマンドにつけてください。

### Rails での利用方法

すべてのモデル、テスト、フィクスチャ、ファクトリに注釈をつける。

    cd /path/to/app
    annotate

モデル、テスト、ファクトリのみに注釈をつける。

    annotate --models --exclude fixtures

モデルのみに注釈をつける。

    annotate --models

routes.rb に注釈をつける。

    annotate --routes

モデル、テスト、フィクスチャ、ファクトリ、シリアライザの注釈を削除する。

    annotate --delete

routes.rb の注釈を削除する。

    annotate --routes --delete

`db:migrate` を実行するたびに自動的に注釈をつけるためには、
`rails g annotate:install` を実行するか、`Rakefile` に `Annotate.load_tasks` を追加してください。

詳細は [Rails における設定](#rails-における設定) をご覧ください。

### Rails の外での利用方法

`--routes` オプションが意味をなさないことを除けば Rails 外の利用でも上述のすべてが適用されます。明示的に1つあるいは複数の `--require` オプションと `--model-dir` オプションを設定することで、`annotate` にプロジェクトの構造を知らせ、プロジェクトが起動し関連のあるコードを読み込むことを助ける必要があります。

## 設定

もし特定のモデルで注釈を常に飛ばしたいときは、モデルファイルの任意の場所に下記の文字列を追加してください。

    # -*- SkipSchemaAnnotations

### Rails における設定

設定ファイル（`.rake` ファイル形式）を生成して、デフォルトオプションを設定するためには下記のコマンドを実行してください。

    rails g annotate:install


このファイルを編集することで、注釈がファイルの上下どちらに追加されるかや、どのタイプのファイルに注釈が記載されるかといったような、出力形式などを制御します。

生成される rake ファイルである `lib/tasks/auto_annotate_models.rake` は `Annotate.load_tasks` も含みます。この rake ファイルはコマンドラインの機能と重複するいくつかの rake タスクを追加します。

    rake annotate_models                          # Add schema information (as comments) to model and fixture files
    rake annotate_routes                          # Adds the route map to routes.rb
    rake remove_annotation                        # Remove schema information from model and fixture files

デフォルトでは、一旦設定ファイルを生成したあとは、`rake db:migrate` が実行されるたびに annotate が実行されます（development 環境のみ）。
この挙動を永続的に無効にしたいときは、`.rake` ファイルを編集し、下記のように変更してください。

```ruby
    'skip_on_db_migrate'   => 'false',
```

上記の記述から下記の記述へ変更する。

```ruby
    'skip_on_db_migrate'   => 'true',
```

1回だけ annotate なしで `rake db:migrate` を実行したいときは、`.rake` ファイルを編集する代わりにシンプルな環境変数をつけることでそれを実現できます。

    ANNOTATE_SKIP_ON_DB_MIGRATE=1 rake db:migrate

## オプション

### `--additional-file-patterns`

コンマで区切った注釈を行う追加のファイルパスあるいは glob(例: `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)を記載する。

### `-d, --delete`

すべてのモデルファイルあるいは routes.rb ファイルから注釈を削除する。

###  `-p [before|top|after|bottom], --position`

model/test/fixture/factory/route/serializer ファイルの上部（前）あるいは下部（後）に注釈を置く。

### `--pc, --position-in-class [before|top|after|bottom]`

model ファイルの上部（前）あるいは下部（後）に注釈を置く。

### `--pf, --position-in-factory [before|top|after|bottom]`

factory ファイルの上部（前）あるいは下部（後）に注釈を置く。

### `--px, --position-in-fixture [before|top|after|bottom]`

fixture ファイルの上部（前）あるいは下部（後）に注釈を置く。

### `--pt, --position-in-test [before|top|after|bottom]`

test ファイルの上部（前）あるいは下部（後）に注釈を置く。

### `--pr, --position-in-routes [before|top|after|bottom]`

routes.rb ファイルの上部（前）あるいは下部（後）に注釈を置く。

### `--ps, --position-in-serializer [before|top|after|bottom]`

serializer ファイルの上部（前）あるいは下部（後）に注釈を置く。

### `--w, --wrapper STR`

パラメーターとして渡されたテキストで注釈をラップします。
--w が使用された場合は、同じテキストが始端と終端に使用されます。

### `--wo, --wrapper-open STR`

注釈の始端をラップするテキスト。

### `--wc, --wrapper-close STR`

注釈の終端をラップするテキスト。

### `-r, --routes`

'rake routes'　の出力で routes.rb に注釈を付ける。

### `--models`

ActiveRecord モデルに注釈を付ける。

### `-a, --active-admin`

active_admin モデルに注釈を付ける。

### `-v, --version`

この gem の現在のバージョンを表示する。

### `-m, --show-migration`

注釈にマイグレーションのバージョン番号を含める。

### `-k, --show-foreign-keys`

注釈にテーブルの外部キー制約の一覧を載せる。

### `--ck, --complete-foreign-keys`

注釈に完全な外部キーの名前を載せる。

### `-i, --show-indexes`

注釈にテーブルのインデックスの一覧を載せる。

### `-s, --simple-indexes`

注釈内のカラムの関連したインデックスを結合する。

### `--model-dir dir`

app/models ではないディレクトリに保存されたモデルファイルに注釈を付ける。ディレクトリ名はカンマで区切る。

### `--root-dir dir`

ルートディレクトリのプロジェクト内に保存されたファイルに注釈を付ける。ディレクトリ名はカンマで区切る。

### `--ignore-model-subdirects`

モデルディレクトリのサブディレクトリを無視する。

### `--sort`

作成順ではなくアルファベット順でカラムをソートする。

### `--classified-sort`

アルファベット順にカラムをソートする。ただし、一番目には id 、その次が残りのカラム、タイムスタンプカラム、関連付けカラムの順となる。

### `-R, --require path`

モデルを読み込む前に必要とする追加のファイル。このファイルは複数回使用される。

### `-e [tests,fixtures,factories,serializers], --exclude`

tests,fixtures,factories,serializers ファイルに注釈を付けないようにする。

### `-f [bare|rdoc|yard|markdown], --format`

プレインテキスト/RDoc/YARD/Markdown としてスキーマ情報を記述する。

### `--force`

変更がない場合でも新しい注釈を強制的に記述する。

### `--frozen`

注釈の変更を許可しない。ファイルに変更がある場合は、ゼロ以外の値で終了します。

### `--timestamp`

注釈にタイムスタンプを含ませる。

### `--trace`

ファイルに注釈を付けられない場合は、例外メッセージだけでなく、スタックトレース全体を表示する。

### `-I, --ignore-columns REGEX`

与えられた正規表現に合致するカラムに注釈をつけないようにする（例: `annotate -I '^(id|updated_at|created_at)'`）。

### `--ignore-routes REGEX`

与えられた正規表現に合致する routes に注釈をつけないようにする（例: `annotate -I '(mobile|resque|pghero)'`）。

### `--hide-limit-column-types VALUES`

与えられたカラムタイプに limit 値を表示させない。カラムタイプはコンマで区切る（例: `integer,boolean,text`）。

### `--hide-default-column-types VALUES`

与えられたカラムタイプに default 値を表示させない。カラムタイプはコンマで区切る（例: `json,jsonb,hstore`）。

### `--ignore-unknown-models`

不正なモデルファイルに対して警告を表示させない。

### `--with-comment`

モデルの注釈にデータベースコメントを含める。


### オプション: `additional_file_patterns`

CLI: `--additional-file-patterns`<br>
Ruby: `:additional_file_patterns`

注釈を行うために追加のパスを提供します。このパスは glob を含むことができます。絶対パスを使用することを推奨します。下記に例を記載します。

*   `/app/lib/decorates/%MODEL_NAME%/*.rb`
*   `/app/lib/forms/%PLURALIZED_MODEL_NAME%/**/*.rb`
*   `/app/lib/forms/%TABLE_NAME%/*.rb`

適切なモデルは `%*%` 構文を用いて推論され、一致するファイルに注釈が付けられます。これは既存のファイル名解決とともに動作します（`annotate_models.rb` の `resolve_filename` メソッドの中で発見されるオプション）。

Rails の設定の中で使用するときは、下記を使用できます。

`File.join(Rails.application.root,
'app/lib/forms/%PLURALIZED_MODEL_NAME%/***/**.rb')`

## ソート

デフォルトでは、カラムはデータベース順でソートされます（つまりマイグレーションが行われた順番）。

もしアルファベット順にソートしてマイグレーションを実行した順番とは関係なく注釈の結果を一致させたいときは、`--sort` オプションを使用してください。

## マークダウン

生成されるフォーマットは実際には MultiMarkdown で、テーブルのための構文拡張機能を利用しています。もしこのフォーマットを使用したいときはパーサーとして `kramdown` を使用することを推奨しています。もしドキュメントを生成するために `yard` を使用している場合は、`.yardopts` ファイルに `kramdown` を追加することでプロバイダとして `kramdown` をマークダウンのフォーマットに指定してください。

    --markup markdown
    --markup-provider kramdown

`Gemfile` にも同様に kramdown を追加するようにしてください。

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

## 警告

**自動作成されたコメントブロックの後にテキストを追加しないでください。**annotate によって以前にコメントブロックが追加された可能性があるとき、annotate はモデル内の始端・終端のコメントブロックを削除することがあります。

annotate が行った変更を必ず確認するようにしてください。Git を使用している場合は、`annotate` を実行した後にプロジェクトのステータスを確認することができます。

    $ git status

VCS（Git や Subversion など）を使っていない人は、特に注意して annotate を扱い、1つの VCS の利用を検討してください。

## リンク集

*   Factory Bot: http://github.com/thoughtbot/factory_bot
*   Object Daddy: http://github.com/flogic/object_daddy
*   Machinist: http://github.com/notahat/machinist
*   Fabrication: http://github.com/paulelliott/fabrication
*   SpatialAdapter: http://github.com/pdeffendol/spatial_adapter
*   PostgisAdapter: http://github.com/nofxx/postgis_adapter
*   PostGISAdapter: https://github.com/dazuma/activerecord-postgis-adapter

## ライセンス

Ruby と同じライセンスでリリースしています。サポートと保証はありません。

## 作者

[AUTHORS.md](https://github.com/ctran/annotate_models/blob/develop/AUTHORS.md) をご覧ください。