[#643] support sql comments

hobo/rails_generators/hobo_front_controller/templates/summary.dryml

@@ -67,11 +67,12 @@
 
     <h2>Models</h2>
     <table class="app-summary">
-      <tr><th>Class</th><th>Table</th></tr>
+      <tr><th>Class</th><th>Table</th><th></th></tr>
       <with-models>
         <tr>
           <td><model-name/></td>
           <td><model-table-name/></td>
+          <td><model-table-comment/></td>
         </tr>
       </with-models>
     </table>        
@@ -80,10 +81,11 @@
       <h3 if="&this.try.table_name"><model-name /></h3>
       <table class="app-summary">
         <with-model-columns>
-          <tr if="&first_item?"><th>Column</th><th>Type</th></tr>
+          <tr if="&first_item?"><th>Column</th><th>Type</th><th></th></tr>
           <tr>
             <td><model-column-name/></td>
             <td><model-column-type/></td>
+            <td><model-column-comment/></td>
           </tr>
         </with-model-columns>
       </table>

hobo/taglibs/rapid_summary.dryml

@@ -256,6 +256,11 @@
   <%= this.try.table_name -%>
 </def>
 
+<!-- given a model, returns the table comment, if it exists and if you have the activerecord-comments plugin installed. -->
+<def tag="model-table-comment">
+  <%= this.try.comment -%>
+</def>
+
 <!-- given a model, repeats on the database columns -->
 <def tag="with-model-columns">
   <repeat with="&this.try.content_columns">
@@ -273,6 +278,12 @@
   <%= this.name -%>
 </def>
 
+<!-- given a column in the context and the model as an attribute, returns the comment for the column.  It returns the SQL comment if that is available (using the activerecord-comments plugin).  If that is not available, it returns the HoboFields comment.  -->
+
+<def tag="model-column-comment" attrs="model">
+  <%= this.try.comment || model.try.field_specs.try.get(this.name).try.comment -%>
+</def>
+
 <!-- given a model, repeats on the associations -->
 <def tag="with-model-associations">
   <repeat with="&this.try.reflect_on_all_associations">

hobofields/lib/hobo_fields/field_spec.rb

@@ -60,6 +60,10 @@ def null
     def default
       options[:default]
     end
+
+    def comment
+      options[:comment]
+    end
 
     def same_type?(col_spec)
       t = sql_type
@@ -74,6 +78,12 @@ def same_type?(col_spec)
 
     def different_to?(col_spec)
       !same_type?(col_spec) ||
+        # we should be able to use col_spec.comment, but col_spec has
+        # a nil table_name for some strange reason.
+        begin
+          col_comment = ActiveRecord::Base.try.column_comment(col_spec.name, model.table_name)
+          col_comment != nil && col_comment != comment
+        end ||
         begin
           check_attributes = [:null, :default]
           check_attributes += [:precision, :scale] if sql_type == :decimal && !col_spec.is_a?(SQLITE_COLUMN_CLASS)  # remove when rails fixes https://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets/2872

hobofields/lib/hobo_fields/migration_generator.rb

@@ -335,6 +335,7 @@ def change_table(model, current_table_name)
           change_spec[:scale]     = spec.scale     unless spec.scale.nil?
           change_spec[:null]      = spec.null      unless spec.null && col.null
           change_spec[:default]   = spec.default   unless spec.default.nil? && col.default.nil?
+          change_spec[:comment]   = spec.comment   unless spec.comment.nil? && col.try.comment.nil?
 
           changes << "change_column :#{new_table_name}, :#{c}, " +
             ([":#{spec.sql_type}"] + format_options(change_spec, spec.sql_type, true)).join(", ")

hobofields/test/migration_generator.rdoctest

@@ -666,8 +666,71 @@ HoboFields has some support for legacy keys.
     =>
      "rename_column :adverts, :id, :advert_id
 
+    >> nuke_model_class(Advert)
+    >> nuke_model_class(Ad)
+    >> ActiveRecord::Base.connection.execute "drop table `adverts`;"
+{.hidden}
+
+
+## Comments
+
+Comments can be added to tables and fields with HoboFields.
+
+    >>
+     class Product < ActiveRecord::Base
+       fields do
+         name :string, :comment => "short name"
+         description :string
+       end
+     end
+    >> up, down = HoboFields::MigrationGenerator.run
+    >> up
+    => 
+     'create_table :products do |t|
+       t.string :name, :comment => "short name"
+       t.string :description
+     end'
+    >> migrate
+
+These comments will be saved to your schema if you have the [column_comments](http://github.com/bryanlarsen/column_comments) plugin installed.  If you do not have this plugin installed, the comments will be available by querying `field_specs`:
+
+    >> Product.field_specs["name"].comment
+    => "short name"
+
+The plugin [activerecord-comments](http://github.com/bryanlarsen/activerecord-comments) may be used to get the comments from the database directly.  If the plugin is installed, use this instead:
+
+    Product.column("name").comment
+
+Because it will be quite common for people not to have both [column_comments](http://github.com/bryanlarsen/column_comments) and [activerecord-comments](http://github.com/bryanlarsen/activerecord-comments) installed, it is impossible for HoboFields to determine the difference between no previous comment and a previously missing plugin.   Therefore, HoboFields will not generate a migration if the only change was to add a comment.  HoboFields will generate a migration for a comment change, but only if the plugin is installed.
+
+    >> require 'activerecord-comments'
+
+    >> # manually add comment as the column_comments plugin would
+    >> Product.connection.execute "alter table `products` modify `name` varchar(255) default null comment 'short name';"
+
+
+    >>
+     class Product < ActiveRecord::Base
+       fields do
+         name :string, :comment => "Short namex"
+         description :string, :comment => "Long name"
+       end
+     end
+    >> up, down = HoboFields::MigrationGenerator.run
+    >> up
+    => "change_column :products, :name, :string, :comment => \"Short namex\", :limit => 255"
+
+
 Cleanup
+{.hidden}
+
+    >> nuke_model_class(Product)
+    >> ActiveRecord::Base.connection.execute "drop table `products`;"
+{.hidden}
+
+Final Cleanup
 {.hidden}
 
     >> system  "mysqladmin #{mysql_login} --force drop #{mysql_database} 2> /dev/null"
 {.hidden}
+