Improve documentation and examples

lib/rubocop/cop/obsession/no_break_or_next.rb

@@ -11,8 +11,8 @@ module Obsession
       # - For small loops, you can just use normal conditions instead of `next`.
       # `break` is allowed.
       #
-      # Note: Sometimes loops can also be rethought, like transforming a `loop`
-      # + `break` into a `while`.
+      # Note: Sometimes loops can also be rethought, like transforming a
+      # `loop` + `break` into a `while`.
       #
       # @example
       #

lib/rubocop/cop/obsession/no_todos.rb

@@ -11,6 +11,19 @@ module Obsession
       # stale TODOs. Sometimes developers really mean to work on their TODOs
       # soon, but then Product re-prioritizes their work, or the developer
       # leaves the company, and never gets a chance to tackle them.
+      #
+      # @example
+      #
+      #   # bad
+      #   # TODO: remove this method when we ship the new signup flow
+      #   def my_method
+      #     ...
+      #   end
+      #
+      #   # good
+      #   def my_method
+      #     ...
+      #   end
       class NoTodos < Base
         MSG = 'Avoid TODO comment, create a task in your project management tool instead.'
         KEYWORD_REGEX = /(^|[^\w])(TODO|FIXME|OPTIMIZE|HACK)($|[^\w])/i

lib/rubocop/cop/obsession/rails/fully_defined_json_field.rb

@@ -18,14 +18,18 @@ module Rails
         # @example
         #
         #   # bad
-        #   add_column :languages, :items, :jsonb
+        #   def change
+        #     add_column :languages, :items, :jsonb
+        #   end
         #
         #   # good
-        #   add_column :languages,
-        #              :items,
-        #              :jsonb,
-        #              default: [],
-        #              comment: "Example: [{ 'name': 'ruby' }, { 'name': 'python' }]"
+        #   def change
+        #     add_column :languages,
+        #                :items,
+        #                :jsonb,
+        #                default: [],
+        #                comment: "Example: [{ 'name': 'ruby' }, { 'name': 'python' }]"
+        #   end
         class FullyDefinedJsonField < Base
           def_node_matcher :json_field?, <<~PATTERN
             (send nil? :add_column _ _ (sym {:json :jsonb}) ...)

lib/rubocop/cop/obsession/rails/no_callback_conditions.rb

@@ -19,12 +19,14 @@ module Rails
         #
         #   # bad
         #   after_update_commit :crawl_rss, if: :rss_changed?
+        #
         #   def crawl_rss
         #     ...
         #   end
         #
         #   # good
         #   after_update_commit :crawl_rss
+        #
         #   def crawl_rss
         #     return if !rss_changed?
         #     ...

lib/rubocop/cop/obsession/rails/safety_assured_comment.rb

@@ -13,6 +13,23 @@ module Rails
         # of the DB migration. The reason should be detailed and reviewed by a
         # knowledgeable PR reviewer. Failure to follow instructions may bring your
         # app down.
+        #
+        # @example
+        #
+        #   # bad
+        #   class RemoveSourceUrlFromBlogPosts < ActiveRecord::Migration[8.0]
+        #     def change
+        #       safety_assured { remove_column :blog_posts, :source_url }
+        #     end
+        #   end
+        #
+        #   # good
+        #   class RemoveSourceUrlFromBlogPosts < ActiveRecord::Migration[8.0]
+        #     # Safe because this column was ignored with self.ignored_columns in PR #1234
+        #     def change
+        #       safety_assured { remove_column :blog_posts, :source_url }
+        #     end
+        #   end
         class SafetyAssuredComment < Base
           MSG =
             'Add `# Safe because <reason>` comment above safety_assured. ' \

lib/rubocop/cop/obsession/rspec/empty_line_after_final_let.rb

@@ -8,15 +8,17 @@ module Rspec
           #
           # @example
           #
-          #   describe '#domain' do
-          #     context do
-          #       let(:url) { Url.new('http://www.some-site.com/some-page') }
-          #       it { expect(url.domain).to eq 'some-site.com' }
-          #     end
+          #   describe Url do
+          #     describe '#domain' do
+          #       context do
+          #         let(:url) { Url.new('http://www.some-site.com/some-page') }
+          #         it { expect(url.domain).to eq 'some-site.com' }
+          #       end
           #
-          #     context do
-          #       let(:url) { Url.new('some-site.com') }
-          #       it { expect(url.domain).to eq 'some-site.com' }
+          #       context do
+          #         let(:url) { Url.new('some-site.com') }
+          #         it { expect(url.domain).to eq 'some-site.com' }
+          #       end
           #     end
           #   end
           class EmptyLineAfterFinalLet < RSpec::EmptyLineAfterFinalLet