Make comment annotations work (#518)

* Hook up with-comment option to rake tasks and CL.
* with_comment option handles commentless columns.
* Style fixes.

Author: dslh

.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2016-12-17 10:16:05 +0100 using RuboCop version 0.46.0.
+# on 2017-10-13 10:01:18 +0200 using RuboCop version 0.46.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -65,11 +65,6 @@ Lint/HandleExceptions:
   Exclude:
     - 'bin/annotate'
 
-# Offense count: 8
-Lint/IneffectiveAccessModifier:
-  Exclude:
-    - 'lib/annotate/annotate_routes.rb'
-
 # Offense count: 1
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle, SupportedStyles.
@@ -88,62 +83,51 @@ Lint/ShadowingOuterLocalVariable:
   Exclude:
     - 'Rakefile'
 
-# Offense count: 6
+# Offense count: 7
 # Cop supports --auto-correct.
 # Configuration parameters: IgnoreEmptyBlocks, AllowUnusedKeywordArguments.
 Lint/UnusedBlockArgument:
   Exclude:
     - 'bin/annotate'
 
-# Offense count: 1
-# Configuration parameters: ContextCreatingMethods.
-Lint/UselessAccessModifier:
-  Exclude:
-    - 'lib/annotate/annotate_routes.rb'
-
-# Offense count: 17
+# Offense count: 18
 Metrics/AbcSize:
-  Max: 159
+  Max: 142
 
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/BlockLength:
-  Max: 140
+  Max: 142
 
 # Offense count: 2
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 8
+# Offense count: 9
 Metrics/CyclomaticComplexity:
-  Max: 42
+  Max: 36
 
-# Offense count: 350
+# Offense count: 380
 # Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
 # URISchemes: http, https
 Metrics/LineLength:
-  Max: 543
+  Max: 276
 
-# Offense count: 24
+# Offense count: 26
 # Configuration parameters: CountComments.
 Metrics/MethodLength:
-  Max: 79
-
-# Offense count: 1
-# Configuration parameters: CountComments.
-Metrics/ModuleLength:
-  Max: 116
+  Max: 75
 
 # Offense count: 7
 Metrics/PerceivedComplexity:
-  Max: 48
+  Max: 42
 
 # Offense count: 1
 Style/AccessorMethodName:
   Exclude:
     - 'lib/annotate.rb'
 
-# Offense count: 3
+# Offense count: 2
 # Cop supports --auto-correct.
 Style/AlignArray:
   Exclude:
@@ -259,21 +243,14 @@ Style/ExtraSpacing:
     - 'spec/integration/rails_4.2.0/Gemfile'
     - 'spec/integration/rails_4.2.0/config.ru'
 
-# Offense count: 9
+# Offense count: 10
 # Configuration parameters: EnforcedStyle, SupportedStyles.
 # SupportedStyles: format, sprintf, percent
 Style/FormatString:
   Exclude:
     - 'lib/annotate/annotate_models.rb'
     - 'lib/annotate/annotate_routes.rb'
 
-# Offense count: 181
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle, SupportedStyles.
-# SupportedStyles: when_needed, always
-Style/FrozenStringLiteralComment:
-  Enabled: false
-
 # Offense count: 7
 # Configuration parameters: MinBodyLength.
 Style/GuardClause:
@@ -356,16 +333,6 @@ Style/NumericLiterals:
 
 # Offense count: 2
 # Cop supports --auto-correct.
-# Configuration parameters: AutoCorrect, EnforcedStyle, SupportedStyles.
-# SupportedStyles: predicate, comparison
-Style/NumericPredicate:
-  Exclude:
-    - 'spec/**/*'
-    - 'lib/annotate.rb'
-    - 'lib/annotate/annotate_models.rb'
-
-# Offense count: 6
-# Cop supports --auto-correct.
 # Configuration parameters: PreferredDelimiters.
 Style/PercentLiteralDelimiters:
   Exclude:
@@ -458,16 +425,15 @@ Style/SpaceAroundKeyword:
     - 'spec/integration/rails_4.2.0/Gemfile'
     - 'spec/integration/standalone/Gemfile'
 
-# Offense count: 6
+# Offense count: 4
 # Cop supports --auto-correct.
 # Configuration parameters: AllowForAlignment.
 Style/SpaceAroundOperators:
   Exclude:
     - 'lib/annotate/annotate_models.rb'
-    - 'lib/tasks/annotate_models.rake'
     - 'lib/tasks/annotate_routes.rake'
 
-# Offense count: 4
+# Offense count: 1
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle, SupportedStyles.
 # SupportedStyles: space, no_space
@@ -517,14 +483,14 @@ Style/SpaceInsideStringInterpolation:
   Exclude:
     - 'lib/annotate/annotate_models.rb'
 
-# Offense count: 223
+# Offense count: 237
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle, SupportedStyles, ConsistentQuotesInMultiline.
 # SupportedStyles: single_quotes, double_quotes
 Style/StringLiterals:
   Enabled: false
 
-# Offense count: 2
+# Offense count: 1
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle, SupportedStyles.
 # SupportedStyles: single_quotes, double_quotes
@@ -581,7 +547,7 @@ Style/UnneededInterpolation:
   Exclude:
     - 'bin/annotate'
 
-# Offense count: 8
+# Offense count: 4
 # Cop supports --auto-correct.
 Style/UnneededPercentQ:
   Exclude:

bin/annotate

@@ -197,6 +197,10 @@ OptionParser.new do |opts|
   opts.on('--ignore-unknown-models', "don't display warnings for bad model files") do |values|
     ENV['ignore_unknown_models'] = 'true'
   end
+
+  opts.on('--with-comment', "include database comments") do |values|
+    ENV['with_comment'] = 'true'
+  end
 end.parse!
 
 options = Annotate.setup_options(

lib/annotate.rb

@@ -33,7 +33,7 @@ module Annotate
     :timestamp, :exclude_serializers, :classified_sort,
     :show_foreign_keys, :show_complete_foreign_keys,
     :exclude_scaffolds, :exclude_controllers, :exclude_helpers,
-    :exclude_sti_subclasses, :ignore_unknown_models
+    :exclude_sti_subclasses, :ignore_unknown_models, :with_comment
   ].freeze
   OTHER_OPTIONS = [
     :ignore_columns, :skip_on_db_migrate, :wrapper_open, :wrapper_close,

lib/annotate/annotate_models.rb

@@ -224,11 +224,7 @@ def get_schema_info(klass, header, options = {})
       info = "# #{header}\n"
       info << get_schema_header_text(klass, options)
 
-      max_size = klass.column_names.map(&:size).max || 0
-      with_comment = options[:with_comment] && klass.columns.first.respond_to?(:comment)
-      max_size = klass.columns.map{|col| col.name.size + col.comment.size }.max || 0 if with_comment
-      max_size += 2 if with_comment
-      max_size += options[:format_rdoc] ? 5 : 1
+      max_size = max_schema_info_width(klass, options)
       md_names_overhead = 6
       md_type_allowance = 18
       bare_type_allowance = 16
@@ -291,7 +287,7 @@ def get_schema_info(klass, header, options = {})
             end
           end
         end
-        col_name = if with_comment
+        col_name = if with_comments?(klass, options) && col.comment
                      "#{col.name}(#{col.comment})"
                    else
                      col.name
@@ -861,6 +857,28 @@ def silence_warnings
     ensure
       $VERBOSE = old_verbose
     end
+
+    private
+
+    def with_comments?(klass, options)
+      options[:with_comment] &&
+        klass.columns.first.respond_to?(:comment) &&
+        klass.columns.any? { |col| !col.comment.nil? }
+    end
+
+    def max_schema_info_width(klass, options)
+      if with_comments?(klass, options)
+        max_size = klass.columns.map do |column|
+          column.name.size + (column.comment ? column.comment.size : 0)
+        end.max || 0
+        max_size += 2
+      else
+        max_size = klass.column_names.map(&:size).max
+      end
+      max_size += options[:format_rdoc] ? 5 : 1
+
+      max_size
+    end
   end
 
   class BadModelFileError < LoadError

lib/tasks/annotate_models.rake

@@ -47,6 +47,7 @@ task annotate_models: :environment do
   options[:ignore_routes] = ENV.fetch('ignore_routes', nil)
   options[:hide_limit_column_types] = Annotate.fallback(ENV['hide_limit_column_types'], '')
   options[:hide_default_column_types] = Annotate.fallback(ENV['hide_default_column_types'], '')
+  options[:with_comment] = Annotate.fallback(ENV['with_comment'], '')
 
   AnnotateModels.do_annotations(options)
 end

spec/annotate/annotate_models_spec.rb

@@ -888,10 +888,11 @@ def self.when_called_with(options = {})
 
     describe 'with_comment option' do
       mocked_columns_with_comment = [
-        [:id,     :integer, { limit: 8,  comment: 'ID' }],
-        [:active, :boolean, { limit: 1,  comment: 'Active' }],
-        [:name,   :string,  { limit: 50, comment: 'Name' }],
-        [:notes,  :text,    { limit: 55, comment: 'Notes' }]
+        [:id,         :integer, { limit: 8,  comment: 'ID' }],
+        [:active,     :boolean, { limit: 1,  comment: 'Active' }],
+        [:name,       :string,  { limit: 50, comment: 'Name' }],
+        [:notes,      :text,    { limit: 55, comment: 'Notes' }],
+        [:no_comment, :text,    { limit: 20, comment: nil }]
       ]
 
       when_called_with with_comment: 'yes',
@@ -905,6 +906,7 @@ def self.when_called_with(options = {})
         #  active(Active) :boolean          not null
         #  name(Name)     :string(50)       not null
         #  notes(Notes)   :text(55)         not null
+        #  no_comment     :text(20)         not null
         #
       EOS