Fix inline docs for ActiveRecord::Migration methods

Author: nepalez

lib/pg_trunk/operations/check_constraints/add_check_constraint.rb

@@ -1,39 +1,42 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#add_check_constraint(table, expression = nil, **options, &block)
-# Add a check constraint to the table
-#
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] expression (nil) The SQL expression
-# @option [#to_s] :name (nil) The optional name of the constraint
-# @option [Boolean] :inherit (true) If the constraint should be inherited by subtables
-# @option [#to_s] :comment (nil) The comment describing the constraint
-# @yield [Proc] the block with the constraint's definition
-# @yieldparam The receiver of methods specifying the constraint
-#
-# The name of the new constraint can be set explicitly
-#
-#   add_check_constraint :users, "length(phone) > 10",
-#                        name: "phone_is_long_enough",
-#                        inherit: false,
-#                        comment: "Phone is 10+ chars long"
-#
-# The name can also be skipped (it will be generated by default):
-#
-#   add_check_constraint :users, "length(phone) > 1"
-#
-# The block syntax can be used for any argument as usual:
-#
-#   add_check_constraint do |c|
-#     c.table "users"
-#     c.expression "length(phone) > 10"
-#     c.name "phone_is_long_enough"
-#     c.inherit false
-#     c.comment "Phone is 10+ chars long"
+# @!parse
+#   class ActiveRecord::Migration
+#     # Add a check constraint to the table
+#     #
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] expression (nil) The SQL expression
+#     # @option [#to_s] :name (nil) The optional name of the constraint
+#     # @option [Boolean] :inherit (true) If the constraint should be inherited by subtables
+#     # @option [#to_s] :comment (nil) The comment describing the constraint
+#     # @yield [c] the block with the constraint's definition
+#     # @yieldparam Object receiver of methods specifying the constraint
+#     # @return [void]
+#     #
+#     # The name of the new constraint can be set explicitly
+#     #
+#     #   add_check_constraint :users, "length(phone) > 10",
+#     #                        name: "phone_is_long_enough",
+#     #                        inherit: false,
+#     #                        comment: "Phone is 10+ chars long"
+#     #
+#     # The name can also be skipped (it will be generated by default):
+#     #
+#     #   add_check_constraint :users, "length(phone) > 1"
+#     #
+#     # The block syntax can be used for any argument as usual:
+#     #
+#     #   add_check_constraint do |c|
+#     #     c.table "users"
+#     #     c.expression "length(phone) > 10"
+#     #     c.name "phone_is_long_enough"
+#     #     c.inherit false
+#     #     c.comment "Phone is 10+ chars long"
+#     #   end
+#     #
+#     # The operation is always reversible.
+#     def add_check_constraint(table, expression = nil, **options, &block); end
 #   end
-#
-# The operation is always reversible.
-
 module PGTrunk::Operations::CheckConstraints
   # @private
   class AddCheckConstraint < Base

lib/pg_trunk/operations/check_constraints/drop_check_constraint.rb

@@ -1,46 +1,49 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#drop_check_constraint(table, expression = nil, **options, &block)
-# Remove a check constraint from the table
-#
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] expression (nil) The SQL expression
-# @option [Boolean] :if_exists (false) Suppress the error when the constraint is absent
-# @option [#to_s] :name (nil) The optional name of the constraint
-# @option [Boolean] :inherit (true) If the constraint should be inherited by subtables
-# @option [#to_s] :comment (nil) The comment describing the constraint
-# @yield [Proc] the block with the constraint's definition
-# @yieldparam The receiver of methods specifying the constraint
-#
-# Definition for the `drop_check_constraint` operation
-#
-# The constraint can be identified by the table and explicit name
-#
-#   drop_check_constraint :users, name: "phone_is_long_enough"
-#
-# Alternatively the name can be got from the expression.
-# Be careful! the expression must have exactly the same form
-# as stored in the database:
-#
-#   drop_check_constraint :users, "length((phone::text) > 10)"
-#
-# To made operation reversible the expression must be provided:
-#
-#   drop_check_constraint "users" do |c|
-#     c.expression "length((phone::text) > 10)"
-#     c.inherit false
-#     c.comment "The phone is 10+ chars long"
+# @!parse
+#   class ActiveRecord::Migration
+#     # Remove a check constraint from the table
+#     #
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] expression (nil) The SQL expression
+#     # @option [Boolean] :if_exists (false) Suppress the error when the constraint is absent
+#     # @option [#to_s] :name (nil) The optional name of the constraint
+#     # @option [Boolean] :inherit (true) If the constraint should be inherited by subtables
+#     # @option [#to_s] :comment (nil) The comment describing the constraint
+#     # @yield [c] the block with the constraint's definition
+#     # @yieldparam Object receiver of methods specifying the constraint
+#     # @return [void]
+#     #
+#     # Definition for the `drop_check_constraint` operation
+#     #
+#     # The constraint can be identified by the table and explicit name
+#     #
+#     #   drop_check_constraint :users, name: "phone_is_long_enough"
+#     #
+#     # Alternatively the name can be got from the expression.
+#     # Be careful! the expression must have exactly the same form
+#     # as stored in the database:
+#     #
+#     #   drop_check_constraint :users, "length((phone::text) > 10)"
+#     #
+#     # To made operation reversible the expression must be provided:
+#     #
+#     #   drop_check_constraint "users" do |c|
+#     #     c.expression "length((phone::text) > 10)"
+#     #     c.inherit false
+#     #     c.comment "The phone is 10+ chars long"
+#     #   end
+#     #
+#     # The operation can be called with `if_exists` option.
+#     #
+#     #   drop_check_constraint :users,
+#     #                         name: "phone_is_long_enough",
+#     #                         if_exists: true
+#     #
+#     # In this case the operation is always irreversible due to
+#     # uncertainty of the previous state of the database.
+#     def drop_check_constraint(table, expression = nil, **options, &block); end
 #   end
-#
-# The operation can be called with `if_exists` option.
-#
-#   drop_check_constraint :users,
-#                         name: "phone_is_long_enough",
-#                         if_exists: true
-#
-# In this case the operation is always irreversible due to
-# uncertainty of the previous state of the database.
-
 module PGTrunk::Operations::CheckConstraints
   # @private
   class DropCheckConstraint < Base

lib/pg_trunk/operations/check_constraints/rename_check_constraint.rb

@@ -1,35 +1,38 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#rename_check_constraint(table, expression = nil, **options, &block)
-# Rename a check constraint
-#
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] expression (nil) The SQL expression
-# @option [#to_s] :name (nil) The current name of the constraint
-# @option [#to_s] :to (nil) The new name for the constraint
-# @yield [Proc] the block with the constraint's definition
-# @yieldparam The receiver of methods specifying the constraint
-#
-# A constraint can be identified by the table and explicit name
-#
-#   rename_check_constraint :users,
-#                           name: "phone_is_long_enough",
-#                           to: "phones.long_enough"
-#
-# Alternatively the name can be got from the expression.
-# Be careful! the expression must have exactly the same form
-# as stored in the database:
-#
-#   rename_check_constraint :users, "length((phone::text) > 10)",
-#                           to: "long_enough"
-#
-# The name can be reset to auto-generated when
-# the `:to` option is missed or blank:
-#
-#   rename_check_constraint :users, "phone_is_long_enough"
-#
-# The operation is always reversible.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Rename a check constraint
+#     #
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] expression (nil) The SQL expression
+#     # @option [#to_s] :name (nil) The current name of the constraint
+#     # @option [#to_s] :to (nil) The new name for the constraint
+#     # @yield [c] the block with the constraint's definition
+#     # @yieldparam Object receiver of methods specifying the constraint
+#     # @return [void]
+#     #
+#     # A constraint can be identified by the table and explicit name
+#     #
+#     #   rename_check_constraint :users,
+#     #                           name: "phone_is_long_enough",
+#     #                           to: "phones.long_enough"
+#     #
+#     # Alternatively the name can be got from the expression.
+#     # Be careful! the expression must have exactly the same form
+#     # as stored in the database:
+#     #
+#     #   rename_check_constraint :users, "length((phone::text) > 10)",
+#     #                           to: "long_enough"
+#     #
+#     # The name can be reset to auto-generated when
+#     # the `:to` option is missed or blank:
+#     #
+#     #   rename_check_constraint :users, "phone_is_long_enough"
+#     #
+#     # The operation is always reversible.
+#     def rename_check_constraint(table, expression = nil, **options, &block); end
+#   end
 module PGTrunk::Operations::CheckConstraints
   # @private
   class RenameCheckConstraint < Base

lib/pg_trunk/operations/check_constraints/validate_check_constraint.rb

@@ -1,26 +1,29 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#validate_check_constraint(table, expression = nil, **options, &block)
-# Validate an invalid check constraint
-#
-# @param [#to_s] table (nil) The qualified name of the table
-# @param [#to_s] expression (nil) The SQL expression
-# @option [#to_s] :name (nil) The optional name of the constraint
-# @yield [Proc] the block with the constraint's definition
-# @yieldparam The receiver of methods specifying the constraint
-#
-# The invalid constraint can be identified by table and explicit name:
-#
-#   validate_check_constraint :users, name: "phone_is_long_enough"
-#
-# Alternatively it can be specified by expression. In this case
-# you must ensure the expression has the same form as it is stored
-# in the database (after parsing the source).
-#
-#   validate_check_constraint :users, "length((phone::text) > 10)"
-#
-# Notice that it is invertible but the inverted operation does nothing.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Validate an invalid check constraint
+#     #
+#     # @param [#to_s] table (nil) The qualified name of the table
+#     # @param [#to_s] expression (nil) The SQL expression
+#     # @option [#to_s] :name (nil) The optional name of the constraint
+#     # @yield [c] the block with the constraint's definition
+#     # @yieldparam Object receiver of methods specifying the constraint
+#     # @return [void]
+#     #
+#     # The invalid constraint can be identified by table and explicit name:
+#     #
+#     #   validate_check_constraint :users, name: "phone_is_long_enough"
+#     #
+#     # Alternatively it can be specified by expression. In this case
+#     # you must ensure the expression has the same form as it is stored
+#     # in the database (after parsing the source).
+#     #
+#     #   validate_check_constraint :users, "length((phone::text) > 10)"
+#     #
+#     # Notice that it is invertible but the inverted operation does nothing.
+#     def validate_check_constraint(table, expression = nil, **options, &block); end
+#   end
 module PGTrunk::Operations::CheckConstraints
   # @private
   class ValidateCheckConstraint < Base

lib/pg_trunk/operations/composite_types/change_composite_type.rb

@@ -1,56 +1,59 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#change_composite_type(name, **options, &block)
-# Modify a composite type
-#
-# @param [#to_s] name (nil) The qualified name of the type
-# @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
-# @option [#to_s] :comment (nil) The comment describing the constraint
-# @yield [Proc] the block with the type's definition
-# @yieldparam The receiver of methods specifying the type
-#
-# The operation can be used to add, drop, rename or change columns.
-# The comment can be changed as well.
-#
-# Providing a type "paint.colored_point":
-#
-#   create_composite_type "paint.colored_point" do |t|
-#     t.column "color", "text", collation: "en_US"
-#     t.column "x", "integer"
-#     t.column "z", "integer"
+# @!parse
+#   class ActiveRecord::Migration
+#     # Modify a composite type
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the type
+#     # @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
+#     # @option [#to_s] :comment (nil) The comment describing the constraint
+#     # @yield [t] the block with the type's definition
+#     # @yieldparam Object receiver of methods specifying the type
+#     # @return [void]
+#     #
+#     # The operation can be used to add, drop, rename or change columns.
+#     # The comment can be changed as well.
+#     #
+#     # Providing a type "paint.colored_point":
+#     #
+#     #   create_composite_type "paint.colored_point" do |t|
+#     #     t.column "color", "text", collation: "en_US"
+#     #     t.column "x", "integer"
+#     #     t.column "z", "integer"
+#     #   end
+#     #
+#     # After the following change:
+#     #
+#     #   change_composite_type "paint.colored_point" do |t|
+#     #     t.change_column "color", "text", collation: "ru_RU", from_collation: "en_US"
+#     #     t.change_column "x", "bigint", from_type: "integer"
+#     #     t.drop_column "z", "integer"
+#     #     t.add_column "Y", "bigint"
+#     #     t.rename_column "x", to: "X"
+#     #     t.comment "2D point with a color", from: "2D point"
+#     #   end
+#     #
+#     # The definition became:
+#     #
+#     #   create_composite_type "paint.colored_point" do |t|
+#     #     t.column "color", "text", collation: "ru_RU"
+#     #     t.column "X", "bigint"
+#     #     t.column "Y", "integer"
+#     #   end
+#     #
+#     # Notice, that all renames will be done AFTER other changes,
+#     # so in `change_column` you should use the old names.
+#     #
+#     # In several cases the operation is not invertible:
+#     #
+#     # - when a column was dropped
+#     # - when `force: :cascade` option is used (to update
+#     #   objects that use the type)
+#     # - when `if_exists: true` is added to the `drop_column` clause
+#     # - when a previous state of the column type, collation or comment
+#     #   is not specified.
+#     def change_composite_type(name, **options, &block); end
 #   end
-#
-# After the following change:
-#
-#   change_composite_type "paint.colored_point" do |t|
-#     t.change_column "color", "text", collation: "ru_RU", from_collation: "en_US"
-#     t.change_column "x", "bigint", from_type: "integer"
-#     t.drop_column "z", "integer"
-#     t.add_column "Y", "bigint"
-#     t.rename_column "x", to: "X"
-#     t.comment "2D point with a color", from: "2D point"
-#   end
-#
-# The definition became:
-#
-#   create_composite_type "paint.colored_point" do |t|
-#     t.column "color", "text", collation: "ru_RU"
-#     t.column "X", "bigint"
-#     t.column "Y", "integer"
-#   end
-#
-# Notice, that all renames will be done AFTER other changes,
-# so in `change_column` you should use the old names.
-#
-# In several cases the operation is not invertible:
-#
-# - when a column was dropped
-# - when `force: :cascade` option is used (to update
-#   objects that use the type)
-# - when `if_exists: true` is added to the `drop_column` clause
-# - when a previous state of the column type, collation or comment
-#   is not specified.
-
 module PGTrunk::Operations::CompositeTypes
   # @private
   class ChangeCompositeType < Base