pg_comment 0.2.1 → 0.3.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    NGMxNWZlYjYzM2FhOTkyYjQyYmVjMjk4NDM3NTQyY2EyMWJmODFmZg==
-  data.tar.gz: !binary |-
-    NzY1MDg5OGMxOTVhOTBkMDk4MzZkZmVjNjlkYTk5ZDQ4NzdiNmI3ZA==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    YmEyYWMwZWViNmI5ZTYxYzk1MDY2ZTRmMzFlYzk4YmY0ZDM1ODNkMjljMjg0
-    ZjNjZjdiZTcxMmQ3NjU0MWFiOWQ0YzM4MWU3YjljMjEzMTRmYjYyYWU3YWVj
-    ZmFjY2FlNjAzYzFhZDY1MmRjZGM0NmZiMTQ3ZTBmOTZhNjc1MTQ=
-  data.tar.gz: !binary |-
-    NDkwYzc3NGU1YzEwNTNhNDA4NDZhYjRkZjY0ZmRjNTY3MGViYjNjNjE1MTAw
-    MTVkYzI0YWExYjJjNjE4Mjc2NzJhYjAxZmM3NTY1N2FkNGVkYzI0N2Q3ODk3
-    Yzc3Y2ZlMTdmMTc5MjViZTBlMzM2ZmJiNDJkZTYwYzNhYjA3Zjk=
+SHA1:
+  metadata.gz: 2cd7ec32d81c13b03d5ca3a04aa42bbe7b2f3990
+  data.tar.gz: 365f10c5ed8754eaf6c5f2ac660fb3c0a246ae75
+SHA512:
+  metadata.gz: d5982039c216c0035c73c8f23247c305a7085d5acc0055500b15148d7a1707f8e847fa9c3b6c873a03c9f422f1edb523daf185e11b0b67f352f83268aedefc00
+  data.tar.gz: 9ad813903ea33a6aedfd39d7065e3ec6f8c8b5f20275b5fa7156e4ab537269d5d29d102c8e627431ca378398489ee4af45d923d0a5bfc6aa248d0ed61adac75f

data/.gitignore

@@ -5,7 +5,8 @@ pkg/*
 .idea
 .rvmrc
 coverage/*
+.yardoc
 
 spec/dummy/db/*.sqlite3
 spec/dummy/log/*.log
-spec/dummy/tmp/
+spec/dummy/tmp/

data/.rspec

@@ -1,2 +1,4 @@
---colour
---format nested
+--color
+--profile
+--backtrace
+--format documentation

data/Gemfile

@@ -3,8 +3,13 @@ source "http://rubygems.org"
 # Specify your gem's dependencies in pg_comment.gemspec
 gemspec
 
+# Necessary, otherwise Travis:CI gets confused.
 gem 'rspec-rails'
 
+group :development do
+  gem 'yard'
+end
+
 group :test do
   gem 'simplecov', :require => false
 end

data/README.markdown

@@ -99,6 +99,28 @@ change_table :phone_numbers do |t|
 end
 ```
 
+## Testing
+
+Install the development dependencies (you will need to compile the native dependencies
+for Postgres, so make sure your development environment is set up)
+
+    bundle install
+
+Modify the credentials in `spec/dummy/config/database.yml` as needed, then run specs.
+
+    bundle exec rake spec
+
+Test coverage (as measured by SimpleCov) should be 100%
+
+## Contributions
+
+Contributions are welcome and appreciated.  However, before you submit your pull request, please be sure to do the
+following:
+
+* Make sure all specs pass.
+* Make sure you have test coverage for any new features; run `bundle exec rake spec`
+* Make sure any new code has RDoc comments; run `bundle exec yard stats --list-undoc`
+
 ## License
 
 Copyright (c) 2011-2013 Arthur Shagall, Mindflight, Inc.

data/Rakefile

@@ -1,11 +1,10 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
 
-APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
-puts "Loading app rakefile at #{APP_RAKEFILE}"
+APP_RAKEFILE = File.expand_path('../spec/dummy/Rakefile', __FILE__)
 load 'rails/tasks/engine.rake'
 
 desc 'Run specs'
-task 'spec' => ['db:drop', 'db:create', 'db:migrate', 'app:spec']
+task 'spec' => ['db:drop', 'db:create', 'db:migrate', 'app:db:test:load', 'app:spec']
 task :default => :spec
 
 def gemspec
@@ -34,7 +33,7 @@ namespace :git do
     sh "git tag -a #{gem_version_tag} -m \"Version #{gem_version}\""
   end
 
-  desc "Push git tag to GitHub"
+  desc 'Push git tag to GitHub'
   task :push_tags do
     sh 'git push --tags'
   end

data/lib/pg_comment.rb

@@ -1,23 +1,27 @@
-require "pg_comment/version"
+require 'rails'
+require 'pg_comment/version'
 require 'active_support/all'
 
+# 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, tables and indexes. It also dumps those comments into your
+# schema.rb.
 module PgComment
-  extend ActiveSupport::Autoload
-  autoload :Adapter
-  autoload :SchemaDumper
 
-  module ConnectionAdapters
-    extend ActiveSupport::Autoload
-
-    autoload_under 'abstract' do
-      autoload :SchemaDefinitions
-      autoload :SchemaStatements
-    end
+  module ConnectionAdapters # :nodoc:
   end
 
-  module Migration
-    autoload :CommandRecorder, 'pg_comment/migration/command_recorder'
+  module Migration # :nodoc:
   end
 end
 
-require 'pg_comment/engine' if defined?(Rails)
+if defined?(Rails)
+  require 'pg_comment/schema_dumper'
+  require 'pg_comment/migration/command_recorder'
+  require 'pg_comment/connection_adapters/abstract/schema_definitions'
+  require 'pg_comment/connection_adapters/abstract/schema_statements'
+  require 'pg_comment/connection_adapters/postgresql_adapter'
+
+  require 'pg_comment/engine'
+end

data/lib/pg_comment/connection_adapters/abstract/schema_definitions.rb

@@ -1,13 +1,14 @@
 module PgComment
   module ConnectionAdapters
-    module SchemaDefinitions
-      def self.included(base)
+    module SchemaDefinitions # :nodoc:
+      def self.included(base) # :nodoc:
         base::Table.class_eval do
           include PgComment::ConnectionAdapters::Table
         end
       end
     end
 
+    # Extensions to ActiveRecord::ConnectionAdapters::Table
     module Table
       extend ActiveSupport::Concern
 

data/lib/pg_comment/connection_adapters/abstract/schema_statements.rb

@@ -1,15 +1,17 @@
 module PgComment
   module ConnectionAdapters
-    module SchemaStatements
-      def self.included(base)
+    module SchemaStatements # :nodoc:
+      def self.included(base) # :nodoc:
         base::AbstractAdapter.class_eval do
           include PgComment::ConnectionAdapters::AbstractAdapter
         end
       end
     end
 
+    # PgComment method stubs for the abstract connection adapter
     module AbstractAdapter
 
+      # Returns false (default use case)
       def supports_comments?
         false
       end

data/lib/pg_comment/connection_adapters/postgresql_adapter.rb

@@ -1,47 +1,107 @@
 module PgComment
   module ConnectionAdapters
+
+    # Implementation of the comment methods
     module PostgreSQLAdapter
+
+      # Returns +true+, Postgres supports comments
       def supports_comments?
         true
       end
 
+      # Sets a comment on the given table.
+      #
+      # ===== Example
+      # ====== Creating a comment on phone_numbers table
+      #  set_table_comment :phone_numbers, 'This table stores phone numbers that conform to the North American Numbering Plan.'
+      #
+      # @param [String, Symbol] table_name
+      # @param [String, Symbol] comment
       def set_table_comment(table_name, comment)
         sql = "COMMENT ON TABLE #{quote_table_name(table_name)} IS $$#{comment}$$;"
         execute sql
       end
 
+      # Sets a comment on a given column of a given table.
+      #
+      # ===== Example
+      # ====== Creating a comment on npa column of table phone_numbers
+      #  set_column_comment :phone_numbers, :npa, 'Numbering Plan Area Code - Allowed ranges: [2-9] for first digit, [0-9] for second and third digit.'
+      #
+      # @param [String, Symbol] table_name
+      # @param [String, Symbol] column_name
+      # @param [String, Symbol] comment
       def set_column_comment(table_name, column_name, comment)
         sql = "COMMENT ON COLUMN #{quote_table_name(table_name)}.#{quote_column_name(column_name)} IS $$#{comment}$$;"
         execute sql
       end
 
+      # Sets comments on multiple columns.  'comments' is a hash of column_name => comment pairs.
+      #
+      # ===== Example
+      # ====== Setting comments on the columns of the phone_numbers 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'
+      #
+      # @param [String, Symbol] table_name
+      # @param [Hash<Symbol, String>] comments
       def set_column_comments(table_name, comments)
         comments.each_pair do |column_name, comment|
           set_column_comment table_name, column_name, comment
         end
       end
 
+      # Removes any comment from the given table.
+      #
+      # ===== Example
+      # ====== Removing comment from phone numbers table
+      #  remove_table_comment :phone_numbers
+      #
+      # @param [String, Symbol] table_name
       def remove_table_comment(table_name)
         sql = "COMMENT ON TABLE #{quote_table_name(table_name)} IS NULL;"
         execute sql
       end
 
+      # Removes any comment from the given column of a given table.
+      #
+      # ===== Example
+      # ====== Removing comment from the npa column of table phone_numbers
+      #  remove_column_comment :phone_numbers, :npa
+      #
+      # @param [String, Symbol] table_name
+      # @param [String, Symbol] column_name
       def remove_column_comment(table_name, column_name)
         sql = "COMMENT ON COLUMN #{quote_table_name(table_name)}.#{quote_column_name(column_name)} IS NULL;"
         execute sql
       end
 
+      # Removes any comment from the given columns of a given table.
+      #
+      # ===== Example
+      # ====== Removing comment from the npa and nxx columns of table phone_numbers
+      #  remove_column_comments :phone_numbers, :npa, :nxx
+      #
+      # @param [String, Symbol] table_name
+      # @param [*String] column_names
       def remove_column_comments(table_name, *column_names)
         column_names.each do |column_name|
           remove_column_comment table_name, column_name
         end
       end
 
+      # Sets the comment on the given index
+      #
+      # @param [String, Symbol] index_name
+      # @param [String, Symbol] comment
       def set_index_comment(index_name, comment)
         sql = "COMMENT ON INDEX #{quote_string(index_name)} IS $$#{comment}$$;"
         execute sql
       end
 
+      # Removes the comment from the given index
+      #
+      # @param [String, Symbol] index_name
       def remove_index_comment(index_name)
         sql = "COMMENT ON INDEX #{quote_string(index_name)} IS NULL;"
         execute sql
@@ -56,6 +116,9 @@ LEFT OUTER JOIN pg_attribute a ON c.oid = a.attrelid AND a.attnum = d.objsubid
 WHERE c.relkind = 'r'
 ORDER BY c.relname
 =end
+
+      # Loads the comments for the given table from the database
+      # @param [String, Symbol] table_name
       def comments(table_name)
         com = select_all %{
 SELECT a.attname AS column_name, d.description AS comment
@@ -69,6 +132,7 @@ WHERE c.relkind = 'r' AND c.relname = '#{table_name}'
         end
       end
 
+      # Loads index comments from the database
       def index_comments
         com = select_all %{
 SELECT c.relname AS index_name, d.description AS comment
@@ -85,12 +149,3 @@ ORDER BY index_name
     end
   end
 end
-
-[:PostgreSQLAdapter, :JdbcAdapter].each do |adapter|
-  begin
-    ActiveRecord::ConnectionAdapters.const_get(adapter).class_eval do
-      include PgComment::ConnectionAdapters::PostgreSQLAdapter
-    end
-  rescue
-  end
-end

data/lib/pg_comment/engine.rb

@@ -1,4 +1,6 @@
 module PgComment
+
+  # PgComment engine.  See docs on Rails engines.
   class Engine < Rails::Engine
     initializer 'pg_comment.load_adapter' do
       ActiveSupport.on_load :active_record do
@@ -18,10 +20,17 @@ module PgComment
         end
 
         conf_name = ActiveRecord::Base.connection_pool.spec.config[:adapter]
-        if conf_name == 'postgresql' then
-          require 'pg_comment/connection_adapters/postgresql_adapter'
+        if conf_name == 'postgresql' || conf_name == "postgis"
+          ["PostGISAdapter::MainAdapter", "PostgreSQLAdapter", "JdbcAdapter"].each do |adapter|
+            begin
+              ::ActiveRecord::ConnectionAdapters.const_get(adapter).class_eval do
+                include ::PgComment::ConnectionAdapters::PostgreSQLAdapter
+              end
+            rescue
+            end
+          end
         end
       end
     end
   end
-end
+end

data/lib/pg_comment/migration/command_recorder.rb

@@ -1,54 +1,62 @@
 module PgComment
   module Migration
+
+    # PgComment methods for the migration command recorder.  This allows
+    # comment methods to be used in "change" type migrations.
     module CommandRecorder
-      def set_table_comment(*args)
+
+      def set_table_comment(*args) # :nodoc:
         record(:set_table_comment, args)
       end
 
-      def remove_table_comment(*args)
+      def remove_table_comment(*args) # :nodoc:
         record(:remove_table_comment, args)
       end
 
-      def set_column_comment(*args)
+      def set_column_comment(*args) # :nodoc:
         record(:set_column_comment, args)
       end
 
-      def set_column_comments(*args)
+      def set_column_comments(*args) # :nodoc:
         record(:set_column_comments, args)
       end
 
-      def remove_column_comment(*args)
+      def remove_column_comment(*args) # :nodoc:
         record(:remove_column_comment, args)
       end
 
-      def remove_column_comments(*args)
+      def remove_column_comments(*args) # :nodoc:
         record(:remove_column_comments, args)
       end
 
-      def set_index_comment(*args)
+      def set_index_comment(*args) # :nodoc:
         record(:set_index_comment, args)
       end
 
-      def remove_index_comment(*args)
+      def remove_index_comment(*args) # :nodoc:
         record(:remove_index_comment, args)
       end
 
+      # remove_table_comment
       def invert_set_table_comment(args)
         table_name = args.first
         [:remove_table_comment, [table_name]]
       end
 
+      # remove_column_comment
       def invert_set_column_comment(args)
         table_name = args[0]
         column_name = args[1]
         [:remove_column_comment, [table_name, column_name]]
       end
 
+      # remove_column_comments
       def invert_set_column_comments(args)
         i_args = [args[0]] + args[1].collect{|name, _| name  }
         [:remove_column_comments, i_args]
       end
 
+      # remove_index_comment
       def invert_set_index_comment(args)
         index_name = args.first
         [:remove_index_comment, [index_name]]

data/lib/pg_comment/schema_dumper.rb

@@ -1,4 +1,5 @@
 module PgComment
+  # Extensions to the Rails schema dumper
   module SchemaDumper
     extend ActiveSupport::Concern
 
@@ -6,6 +7,7 @@ module PgComment
       alias_method_chain :tables, :comments
     end
 
+    # Support for dumping comments
     def tables_with_comments(stream)
       tables_without_comments(stream)
       @connection.tables.sort.each do |table_name|
@@ -14,16 +16,17 @@ module PgComment
 
       unless (index_comments = @connection.index_comments).empty?
         index_comments.each_pair do |index_name, comment|
-          stream.puts "  set_index_comment '#{index_name}', '#{comment.gsub(/'/, "\\\\'")}'"
+          stream.puts "  set_index_comment '#{index_name}', '#{format_comment(comment)}'"
         end
       end
     end
 
+    # Dumps the comments on a particular table to the stream.
     def dump_comments(table_name, stream)
       unless (comments = @connection.comments(table_name)).empty?
         comment_statements = comments.map do |row|
           column_name = row[0]
-          comment = row[1].gsub(/'/, "\\\\'")
+          comment = format_comment(row[1])
           if column_name
             "  set_column_comment '#{table_name}', '#{column_name}', '#{comment}'"
           else
@@ -37,5 +40,11 @@ module PgComment
       end
     end
     private :dump_comments
+
+    # Escape out single quotes from comments
+    def format_comment(comment)
+      comment.gsub(/'/, "\\\\'")
+    end
+    private :format_comment
   end
 end

data/lib/pg_comment/version.rb

@@ -1,3 +1,4 @@
 module PgComment
-  VERSION = '0.2.1'
+  # PgComment version
+  VERSION = '0.3.0'
 end

data/pg_comment.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
   s.email       = ["arthur.shagall@gmail.com"]
   s.homepage    = "https://github.com/albertosaurus/pg_comment"
   s.summary     = 'Postgres Comments for Rails'
-  s.description = 'Extends Rails migrations to support setting column and table comments.  Pulls out comments into schema.rb'
+  s.description = 'Extends Rails migrations to support setting column and table comments. Pulls out comments into schema.rb'
 
   s.rubyforge_project = "pg_comment"
 
@@ -19,7 +19,7 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_dependency('activerecord', '~> 3.0')
-  s.add_development_dependency('rails', '~> 3.2')
+  s.add_dependency('rails', '~> 3.2')
   s.add_development_dependency('pg')
-  s.add_development_dependency('rspec-rails')
+  s.add_development_dependency('rspec-rails', '~> 3.4')
 end

data/spec/lib/pg_comment/connection_adapters/abstract/schema_statements_spec.rb

@@ -9,7 +9,7 @@ describe PgComment::ConnectionAdapters::AbstractAdapter do
   let(:adapter_stub){ AbstractAdapterStub.new }
 
   it 'should not support comments by default' do
-    adapter_stub.supports_comments?.should be_false
+    expect(adapter_stub.supports_comments?).to eq(false)
   end
 
   it 'should define method stubs for comment methods' do
@@ -20,6 +20,6 @@ describe PgComment::ConnectionAdapters::AbstractAdapter do
       :remove_column_comment,
       :remove_column_comments,
       :set_index_comment,
-      :remove_index_comment ].each { |method_name| adapter_stub.respond_to?(method_name).should be_true }
+      :remove_index_comment ].each { |method_name| expect(adapter_stub.respond_to?(method_name)).to eq(true) }
   end
-end
+end

data/spec/lib/pg_comment/connection_adapters/postgresql_adapter_spec.rb

@@ -16,7 +16,7 @@ describe PgComment::ConnectionAdapters::PostgreSQLAdapter do
   let(:connection){ ConnectionStub.new }
 
   it 'should support comments' do
-    connection.supports_comments?.should be_true
+    expect(connection.supports_comments?).to eq(true)
   end
 
   context 'comment methods' do
@@ -60,4 +60,4 @@ describe PgComment::ConnectionAdapters::PostgreSQLAdapter do
       connection.remove_index_comment :foo
     end
   end
-end
+end

data/spec/spec_helper.rb

@@ -7,8 +7,9 @@ unless ENV['TRAVIS']
   end
 end
 
-require File.expand_path("../dummy/config/environment.rb",  __FILE__)
+require File.expand_path("../dummy/config/environment",  __FILE__)
 require 'rspec/rails'
+require 'pg_comment'
 
 RSpec.configure do |config|
   config.mock_with :rspec

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pg_comment
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Arthur Shagall
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-05 00:00:00.000000000 Z
+date: 2015-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -31,7 +31,7 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '3.2'
-  type: :development
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -42,32 +42,32 @@ dependencies:
   name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
-description: Extends Rails migrations to support setting column and table comments.  Pulls
-  out comments into schema.rb
+        version: '3.4'
+description: Extends Rails migrations to support setting column and table comments.
+  Pulls out comments into schema.rb
 email:
 - arthur.shagall@gmail.com
 executables: []
@@ -139,18 +139,19 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: pg_comment
-rubygems_version: 2.0.3
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Postgres Comments for Rails
 test_files: []
+has_rdoc: