Add opt-in show_indexes_comments option to display index comments

lib/annotate_rb/model_annotator/index_annotation/index_component.rb

@@ -45,16 +45,27 @@ def to_default
             end
           end
 
+          comment_info = ""
+          if options[:show_indexes_comments]
+            value = index.try(:comment).try(:to_s)
+            comment_info = if value.present?
+              " COMMENT #{value}"
+            else
+              ""
+            end
+          end
+
           # standard:disable Lint/FormatParameterMismatch
           sprintf(
-            "#  %-#{max_size}.#{max_size}s %s%s%s%s%s%s",
+            "#  %-#{max_size}.#{max_size}s %s%s%s%s%s%s%s",
             index.name,
             "(#{columns_info.join(",")})",
             include_info,
             unique_info,
             nulls_not_distinct_info,
             where_info,
-            using_info
+            using_info,
+            comment_info
           ).rstrip
           # standard:enable Lint/FormatParameterMismatch
         end
@@ -92,13 +103,24 @@ def to_markdown
             end
           end
 
+          comment_info = ""
+          if options[:show_indexes_comments]
+            value = index.try(:comment).try(:to_s)
+            comment_info = if value.present?
+              " _comment_ #{value}"
+            else
+              ""
+            end
+          end
+
           details = sprintf(
-            "%s%s%s%s%s",
+            "%s%s%s%s%s%s",
             include_info,
             unique_info,
             nulls_not_distinct_info,
             where_info,
-            using_info
+            using_info,
+            comment_info
           ).strip
           details = " (#{details})" unless details.blank?
 

lib/annotate_rb/options.rb

@@ -49,6 +49,7 @@ def from(options = {}, state = {})
       show_check_constraints: false, # ModelAnnotator
       show_foreign_keys: true, # ModelAnnotator
       show_indexes: true, # ModelAnnotator
+      show_indexes_comments: false, # ModelAnnotator
       show_indexes_include: false, # ModelAnnotator
       show_virtual_columns: false, # ModelAnnotator
       simple_indexes: false, # ModelAnnotator
@@ -124,6 +125,7 @@ def from(options = {}, state = {})
       :show_complete_foreign_keys,
       :show_foreign_keys,
       :show_indexes,
+      :show_indexes_comments,
       :show_indexes_include,
       :simple_indexes,
       :sort,

spec/lib/annotate_rb/model_annotator/index_annotation/annotation_builder_spec.rb

@@ -117,6 +117,100 @@
       end
     end
 
+    context "index has a comment" do
+      let(:options) { ::AnnotateRb::Options.new({show_indexes: true, show_indexes_comments: true}) }
+
+      let(:indexes) do
+        [
+          mock_index("index_rails_02e851e3b7", columns: ["id"]),
+          mock_index("index_rails_02e851e3b8",
+            columns: %w[foreign_thing_id],
+            comment: "This is a comment")
+        ]
+      end
+
+      let(:expected_default) do
+        <<~EOS.strip
+          #
+          # Indexes
+          #
+          #  index_rails_02e851e3b7  (id)
+          #  index_rails_02e851e3b8  (foreign_thing_id) COMMENT This is a comment
+        EOS
+      end
+
+      let(:expected_markdown) do
+        <<~EOS.strip
+          #
+          # ### Indexes
+          #
+          # * `index_rails_02e851e3b7`:
+          #     * **`id`**
+          # * `index_rails_02e851e3b8` (_comment_ This is a comment):
+          #     * **`foreign_thing_id`**
+        EOS
+      end
+
+      it "includes the comment in default format" do
+        expect(default_format).to eq(expected_default)
+      end
+
+      it "includes the comment in markdown format" do
+        expect(markdown_format).to eq(expected_markdown)
+      end
+    end
+
+    context "index has a comment but show_indexes_comments is false" do
+      let(:options) { ::AnnotateRb::Options.new({show_indexes: true, show_indexes_comments: false}) }
+
+      let(:indexes) do
+        [
+          mock_index("index_rails_02e851e3b8",
+            columns: %w[foreign_thing_id],
+            comment: "This is a comment")
+        ]
+      end
+
+      let(:expected_result) do
+        <<~EOS.strip
+          #
+          # Indexes
+          #
+          #  index_rails_02e851e3b8  (foreign_thing_id)
+        EOS
+      end
+
+      it "does not include the comment" do
+        expect(default_format).to eq(expected_result)
+      end
+    end
+
+    context "index has a comment and is unique" do
+      let(:options) { ::AnnotateRb::Options.new({show_indexes: true, show_indexes_comments: true}) }
+
+      let(:indexes) do
+        [
+          mock_index("index_rails_02e851e3b7",
+            columns: %w[attested_by_employee_id subject_id subject_type],
+            unique: true,
+            comment: "My explanatory comment")
+        ]
+      end
+
+      let(:expected_result) do
+        <<~EOS.strip
+          #
+          # Indexes
+          #
+          #  index_rails_02e851e3b7  (attested_by_employee_id,subject_id,subject_type) UNIQUE COMMENT My explanatory comment
+        EOS
+      end
+
+      it "shows both UNIQUE and COMMENT" do
+        expect(default_format).to eq(expected_result)
+      end
+    end
+
     context "index includes has a string form" do
       let(:indexes) do
         [

spec/support/annotate_test_helpers.rb

@@ -24,7 +24,8 @@ def mock_index(name, params = {})
       nulls_not_distinct: params[:nulls_not_distinct] || false,
       orders: params[:orders] || {},
       where: params[:where],
-      using: params[:using])
+      using: params[:using],
+      comment: params[:comment])
   end
 
   def mock_foreign_key(name, from_column, to_table, to_column = "id", constraints = {})