<commit_before>= PgComment

In any PostgreSQL database where the Rails app is not the only consumer, it is very helpful to have comments on the various database entities.  PgComment adds methods to migrations to set and remove comments on columns and tables.

Obviously, only the PostgreSQL adapter is supported.

== Warning

This is still somewhat experimental.  It has to date been tested with:

* Ruby
  - 1.8.7 REE
  - 1.9.2 YARV
  - JRuby 1.6.4
* Rails
  - 3.0.10
  - 3.1

All bug reports are welcome.

== Installation

Assuming you're using RubyGems:

    gem install pg_comment

== Usage

PgComment adds five methods to migrations:

* set_table_comment(table_name, comment)
* remove_table_comment(table_name)
* set_column_comment(table_name, column_name, comment)
* remove_column_comment(table_name, column_name, comment)
* set_column_comments(table_name, comments)

Set a comment on the given table.

    set_table_comment :phone_numbers, 'This table stores phone numbers that conform to the North American Numbering Plan.'

Sets a comment on a given column of a given table.

    set_column_comment :phone_numbers, :npa, 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.'

Removes any comment from the given table.

    remove_table_comment :phone_numbers

Removes any comment from the given column of a given table.

    remove_column_comment :phone_numbers, :npa

Set comments on multiple columns in the table.

    set_column_comments :phone_numbers, :npa => 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.',
                                        :nxx => 'Central Office Number'

PgComment also adds extra methods to change_table.

Set comments:

    change_table :phone_numbers do |t|
        t.set_table_comment 'This table stores phone numbers that conform to the North American Numbering Plan.'
        t.set_column_comment :npa, 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.'
    end

    change_table :phone_numbers do |t|
        t.set_column_comments :npa => 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.',
                              :nxx => 'Central Office Number'
    end

Remove comments:

    change_table :phone_numbers do |t|
        t.remove_table_comment
        t.remove_column_comment :npa
    end

== License

Copyright (c) 2011 <NAME>
<commit_msg>Updated documentation in the README file.<commit_after>= PgComment

In any PostgreSQL database where the Rails app is not the only consumer, it is very helpful to have comments on the various elements of the schema.  PgComment extends the migrations DSL with methods to set and remove comments on columns and tables.  It also dumps those comments into your schema.rb.

Obviously, only the PostgreSQL adapter is supported.

== Warning

This is still somewhat experimental.  It has to date been tested with:

* Ruby
  - 1.8.7 REE
  - 1.9.2 YARV
  - JRuby 1.6.4
* Rails
  - 3.0.10
  - 3.1

All bug reports are welcome.

== Installation

Add the following to the Gemfile of your Rails app:

    gem 'pg_comment'

Alternatively you can manually install from RubyGems:

    gem install pg_comment

== Usage

PgComment adds five methods to migrations:

* set_table_comment(table_name, comment)
* remove_table_comment(table_name)
* set_column_comment(table_name, column_name, comment)
* remove_column_comment(table_name, column_name, comment)
* set_column_comments(table_name, comments)
* remove_column_comments(table_name, *comments)

=== Examples

Set a comment on the given table.

    set_table_comment :phone_numbers, 'This table stores phone numbers that conform to the North American Numbering Plan.'

Sets a comment on a given column of a given table.

    set_column_comment :phone_numbers, :npa, 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.'

Removes any comment from the given table.

    remove_table_comment :phone_numbers

Removes any comment from the given column of a given table.

    remove_column_comment :phone_numbers, :npa

Set comments on multiple columns in the table.

    set_column_comments :phone_numbers, :npa => 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.',
                                        :nxx => 'Central Office Number'

Remove comments from multiple columns in the table.

    remove_column_comments :phone_numbers, :npa, :nxx

PgComment also adds extra methods to change_table.

Set comments:

    change_table :phone_numbers do |t|
        t.set_table_comment 'This table stores phone numbers that conform to the North American Numbering Plan.'
        t.set_column_comment :npa, 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.'
    end

    change_table :phone_numbers do |t|
        t.set_column_comments :npa => 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.',
                              :nxx => 'Central Office Number'
    end

Remove comments:

    change_table :phone_numbers do |t|
        t.remove_table_comment
        t.remove_column_comment :npa
    end

    change_table :phone_numbers do |t|
      t.remove_column_comments :npa, :nxx
    end

== License

Copyright (c) 2011 <NAME>

{'fraction_non_alphanumeric': 0.06825688073394495, 'fraction_numerical': 0.012844036697247707, 'mean_word_length': 3.438925081433225, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5340257', 'n_tokens_mistral': 1652, 'n_tokens_neox': 1572, 'n_words': 647}