pg_trunk 0.1.0 → 0.2.0

data/lib/pg_trunk/operations/composite_types/drop_composite_type.rb

@@ -1,49 +1,54 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#drop_composite_type(name, **options, &block)
-# Drop a composite type
-#
-# @param [#to_s] name (nil) The qualified name of the type
-# @option [Boolean] :if_exists (false) Suppress the error when the type is absent
-# @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 drops a composite_type type identified by its
-# qualified name (it can include a schema).
-#
-# For inversion use the same options as in the
-# `create_composite_type` operation.
-#
-#   drop_composite_type "paint.colored_point" do |d|
-#     d.column "x", "integer"
-#     d.column "y", "integer"
-#     d.column "color", "text", collation: "en_US"
-#     d.comment <<~COMMENT
-#       2D point with color
-#     COMMENT
+# @!parse
+#   class ActiveRecord::Migration
+#     # Drop a composite type
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the type
+#     # @option options [Boolean] :if_exists (false) Suppress the error when the type is absent
+#     # @option options [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
+#     # @option options [#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 drops a composite_type type identified by its qualified name (it can include a schema).
+#     #
+#     # For inversion use the same options as in the `create_composite_type` operation.
+#     #
+#     # ```ruby
+#     # drop_composite_type "paint.colored_point" do |d|
+#     #   d.column "x", "integer"
+#     #   d.column "y", "integer"
+#     #   d.column "color", "text", collation: "en_US"
+#     #   d.comment <<~COMMENT
+#     #     2D point with color
+#     #   COMMENT
+#     # end
+#     # ```
+#     #
+#     # Notice, that the composite type creation can use no attributes.
+#     # That's why dropping it is always reversible; though the reversion provides a type without columns:
+#     #
+#     # ```ruby
+#     # drop_composite_type "paint.colored_point"
+#     # ```
+#     #
+#     # With the `force: :cascade` option the operation removes all objects using the type.
+#     #
+#     # ```ruby
+#     # drop_composite_type "paint.colored_point", force: :cascade
+#     # ```
+#     #
+#     # With the `if_exists: true` option the operation won't fail even when the view was absent.
+#     #
+#     # ```ruby
+#     # drop_composite_type "paint.colored_point", if_exists: true
+#     # ```
+#     #
+#     # Both options make a migration irreversible due to uncertainty of the previous state of the database.
+#     def drop_composite_type(name, **options, &block); end
 #   end
-#
-# Notice, that the composite type creation can use no attributes.
-# That's why dropping it is always reversible; though the reversion
-# would provide a type without columns:
-#
-#   drop_composite_type "paint.colored_point"
-#
-# With the `force: :cascade` option the operation would remove
-# all objects using the type.
-#
-#   drop_composite_type "paint.colored_point", force: :cascade
-#
-# With the `if_exists: true` option the operation won't fail
-# even when the view was absent in the database.
-#
-#   drop_composite_type "paint.colored_point", if_exists: true
-#
-# Both options make a migration irreversible due to uncertainty
-# of the previous state of the database.
-
 module PGTrunk::Operations::CompositeTypes
   # @private
   class DropCompositeType < Base

data/lib/pg_trunk/operations/composite_types/rename_composite_type.rb

@@ -1,17 +1,20 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#rename_composite_type(name, to:)
-# Change the name and/or schema of a composite type
-#
-# @param [#to_s] name (nil) The qualified name of the type
-# @option [#to_s] :to (nil) The new qualified name for the type
-#
-# @example
-#
-#   rename_composite_type "point", to: "paint.colored_point"
-#
-# The operation is always reversible.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Change the name and/or schema of a composite type
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the type
+#     # @option options [#to_s] :to (nil) The new qualified name for the type
+#     # @return [void]
+#     #
+#     # ```ruby
+#     # rename_composite_type "point", to: "paint.colored_point"
+#     # ```
+#     #
+#     # The operation is always reversible.
+#     def rename_composite_type(name, to:); end
+#   end
 module PGTrunk::Operations::CompositeTypes
   # @private
   class RenameCompositeType < Base

data/lib/pg_trunk/operations/domains/change_domain.rb

@@ -1,53 +1,59 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#change_domain(name, &block)
-# Modify a domain type
-#
-# @param [#to_s] name (nil) The qualified name of the type
-# @yield [Proc] the block with the type's definition
-# @yieldparam The receiver of methods specifying the type
-#
-# The operation can be used to add or remove constraints,
-# modify the default_sql value, or the description of the domain type.
-# Neither the underlying type nor the collation can be changed.
-#
-#   change_domain "dict.us_postal_code" do |d|
-#     d.null true # from: false
-#     # check is added for inversion
-#     d.drop_constraint "postal_code_length", check: <<~SQL
-#       length(VALUE) > 3 AND length(VALUE) < 6
-#     SQL
-#     d.add_constraint <<~SQL, name: "postal_code_valid"
-#       VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'
-#     SQL
-#     d.default_sql "'00000'::text", from: "'0000'::text"
-#     d.comment <<~COMMENT, from: <<~COMMENT
-#       Supported currencies
-#     COMMENT
-#       Currencies
-#     COMMENT
+# @!parse
+#   class ActiveRecord::Migration
+#     # Modify a domain type
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the type
+#     # @yield [d] the block with the type's definition
+#     # @yieldparam Object receiver of methods specifying the type
+#     # @return [void]
+#     #
+#     # The operation can be used to add or remove constraints,
+#     # modify the default_sql value, or the description of the domain type.
+#     # Neither the underlying type nor the collation can be changed.
+#     #
+#     # ```ruby
+#     # change_domain "dict.us_postal_code" do |d|
+#     #   d.null true # from: false
+#     #   # check is added for inversion
+#     #   d.drop_constraint "postal_code_length", check: <<~SQL
+#     #     length(VALUE) > 3 AND length(VALUE) < 6
+#     #   SQL
+#     #   d.add_constraint <<~SQL, name: "postal_code_valid"
+#     #     VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'
+#     #   SQL
+#     #   d.default_sql "'00000'::text", from: "'0000'::text"
+#     #   d.comment <<~COMMENT, from: <<~COMMENT
+#     #     Supported currencies
+#     #   COMMENT
+#     #     Currencies
+#     #   COMMENT
+#     # end
+#     # ```
+#     #
+#     # Use blank string (not a `nil` value) to reset either a default_sql,
+#     # or the comment. `nil`-s here will be ignored.
+#     #
+#     # When dropping a constraint you can use a `check` expression.
+#     # In the same manner, use `from` option with `comment` or `default_sql`
+#     # to make the operation invertible.
+#     #
+#     # It is irreversible in case any `drop_constraint` clause
+#     # has `if_exists: true` or `force: :cascade` option -- due to
+#     # uncertainty of the previous state of the database:
+#     #
+#     # ```ruby
+#     # change_domain "dict.us_postal_code", force: :cascade do |d|
+#     #   d.drop_constraint "postal_code_valid" # missed `:check` option
+#     #   d.drop_constraint "postal_code_length"
+#     #   d.drop_constraint "postal_code_format", if_exists: true
+#     #   d.default_sql "'0000'::text" # missed `:from` option
+#     #   d.comment "New comment" # missed `:from` option
+#     # end
+#     # ```
+#     def change_domain(name, &block); end
 #   end
-#
-# Use blank string (not a `nil` value) to reset either a default_sql,
-# or the comment. `nil`-s here will be ignored.
-#
-# When dropping a constraint you can use a `check` expression.
-# In the same manner, use `from` option with `comment` or `default_sql`
-# to make the operation invertible.
-#
-# It is irreversible in case any `drop_constraint` clause
-# has `if_exists: true` or `force: :cascade` option -- due to
-# uncertainty of the previous state of the database:
-#
-#   # Irreversible change
-#   change_domain "dict.us_postal_code", force: :cascade do |d|
-#     d.drop_constraint "postal_code_valid" # missed `:check` option
-#     d.drop_constraint "postal_code_length"
-#     d.drop_constraint "postal_code_format", if_exists: true
-#     d.default_sql "'0000'::text" # missed `:from` option
-#     d.comment "New comment" # missed `:from` option
-#   end
-
 module PGTrunk::Operations::Domains
   # @private
   class ChangeDomain < Base

data/lib/pg_trunk/operations/domains/create_domain.rb

@@ -1,31 +1,34 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#create_domain(name, **options, &block)
-# Create a domain type
-#
-# @param [#to_s] name (nil) The qualified name of the type
-# @option [#to_s] :as (nil) The base type for the domain (alias: :type)
-# @option [#to_s] :collation (nil) The collation
-# @option [Boolean] :null (true) If a value of this type can be NULL
-# @option [#to_s] :default_sql (nil) The snippet for the default value of the domain
-# @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
-#
-# @example:
-#
-#   create_domain "dict.us_postal_code", as: "text" do |d|
-#     d.collation "en_US"
-#     d.default_sql "'0000'::text"
-#     d.null false
-#     d.constraint <<~SQL, name: "code_valid"
-#       VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'
-#     SQL
-#     d.comment "US postal code"
+# @!parse
+#   class ActiveRecord::Migration
+#     # Create a domain type
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the type
+#     # @option options [#to_s] :as (nil) The base type for the domain (alias: :type)
+#     # @option options [#to_s] :collation (nil) The collation
+#     # @option options [Boolean] :null (true) If a value of this type can be NULL
+#     # @option options [#to_s] :default_sql (nil) The snippet for the default value of the domain
+#     # @option options [#to_s] :comment (nil) The comment describing the constraint
+#     # @yield [d] the block with the type's definition
+#     # @yieldparam Object receiver of methods specifying the type
+#     # @return [void]
+#     #
+#     # ```ruby
+#     # create_domain "dict.us_postal_code", as: "text" do |d|
+#     #   d.collation "en_US"
+#     #   d.default_sql "'0000'::text"
+#     #   d.null false
+#     #   d.constraint <<~SQL, name: "code_valid"
+#     #     VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'
+#     #   SQL
+#     #   d.comment "US postal code"
+#     # end
+#     # ```
+#     #
+#     # It is always reversible.
+#     def create_domain(name, **options, &block); end
 #   end
-#
-# It is always reversible.
-
 module PGTrunk::Operations::Domains
   # @private
   class CreateDomain < Base

data/lib/pg_trunk/operations/domains/drop_domain.rb

@@ -1,47 +1,56 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#drop_domain(name, **options, &block)
-# Drop a domain type by qualified name
-#
-# @param [#to_s] name (nil) The qualified name of the type
-# @option [Boolean] :if_exists (false) Suppress the error when the type is absent
-# @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
-# @option [#to_s] :as (nil) The base type for the domain (alias: :type)
-# @option [#to_s] :collation (nil) The collation
-# @option [#to_s] :default_sql (nil) The snippet for the default value of the domain
-# @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
-#
-# @example:
-#
-#   drop_domain "dict.us_postal_code"
-#
-# To make the operation invertible, use the same options
-# as in the `create_domain` operation.
-#
-#   drop_domain "dict.us_postal_code", as: "string" do |d|
-#     d.constraint <<~SQL, name: "code_valid"
-#       VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'
-#     SQL
-#     d.comment <<~COMMENT
-#       US postal code
-#     COMMENT
+# @!parse
+#   class ActiveRecord::Migration
+#     # Drop a domain type by qualified name
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the type
+#     # @option options [Boolean] :if_exists (false) Suppress the error when the type is absent
+#     # @option options [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
+#     # @option options [#to_s] :as (nil) The base type for the domain (alias: :type)
+#     # @option options [#to_s] :collation (nil) The collation
+#     # @option options [#to_s] :default_sql (nil) The snippet for the default value of the domain
+#     # @option options [#to_s] :comment (nil) The comment describing the constraint
+#     # @yield [d] the block with the type's definition
+#     # @yieldparam Object receiver of methods specifying the type
+#     # @return [void]
+#     #
+#     # ```ruby
+#     # drop_domain "dict.us_postal_code"
+#     # ```
+#     #
+#     # To make the operation invertible, use the same options
+#     # as in the `create_domain` operation.
+#     #
+#     # ```ruby
+#     # drop_domain "dict.us_postal_code", as: "string" do |d|
+#     #   d.constraint <<~SQL, name: "code_valid"
+#     #     VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'
+#     #   SQL
+#     #   d.comment <<~COMMENT
+#     #     US postal code
+#     #   COMMENT
+#     # end
+#     # ```
+#     #
+#     # With the `force: :cascade` option the operation would remove
+#     # all the objects that use the type.
+#     #
+#     # ```ruby
+#     # drop_domain "dict.us_postal_code", force: :cascade
+#     # ```
+#     #
+#     # With the `if_exists: true` option the operation won't fail
+#     # even when the view was absent in the database.
+#     #
+#     # ```ruby
+#     # drop_domain "dict.us_postal_code", if_exists: true
+#     # ```
+#     #
+#     # Both options make a migration irreversible due to uncertainty
+#     # of the previous state of the database.
+#     def drop_domain(name, **options, &block); end
 #   end
-#
-# With the `force: :cascade` option the operation would remove
-# all the objects that use the type.
-#
-#   drop_domain "dict.us_postal_code", force: :cascade
-#
-# With the `if_exists: true` option the operation won't fail
-# even when the view was absent in the database.
-#
-#   drop_domain "dict.us_postal_code", if_exists: true
-#
-# Both options make a migration irreversible due to uncertainty
-# of the previous state of the database.
-
 module PGTrunk::Operations::Domains
   # @private
   class DropDomain < Base

data/lib/pg_trunk/operations/domains/rename_domain.rb

@@ -1,17 +1,22 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#rename_domain(name, to:)
-# Change the name and/or schema of a domain type
-#
-# @param [#to_s] :name (nil) The qualified name of the type
-# @option [#to_s] :to (nil) The new qualified name for the type
-#
-# A domain type can be both renamed and moved to another schema.
-#
-#   rename_domain "us_code", to: "dict.us_postal_code"
-#
-# The operation is always reversible.
-
+# @!parse
+#   class ActiveRecord::Migration
+#     # Change the name and/or schema of a domain type
+#     #
+#     # @param [#to_s] :name (nil) The qualified name of the type
+#     # @option options [#to_s] :to (nil) The new qualified name for the type
+#     # @return [void]
+#     #
+#     # A domain type can be both renamed and moved to another schema.
+#     #
+#     # ```ruby
+#     # rename_domain "us_code", to: "dict.us_postal_code"
+#     # ```
+#     #
+#     # The operation is always reversible.
+#     def rename_domain(name, to:); end
+#   end
 module PGTrunk::Operations::Domains
   # @private
   class RenameDomain < Base

data/lib/pg_trunk/operations/enums/change_enum.rb

@@ -1,38 +1,43 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#change_enum(name, &block)
-# Modify an enumerated type
-#
-# @param [#to_s] name (nil) The qualified name of the type
-# @yield [Proc] the block with the type's definition
-# @yieldparam The receiver of methods specifying the type
-#
-# The operation can be used to rename or add values to the
-# enumerated type. The commend can be changed as well.
-#
-#   change_enum "currencies" do |e|
-#     e.add_value "EUR", after: "BTC"
-#     e.add_value "GBP", before: "usd"
-#     e.add_value "JPY" # to the end of the list
-#     e.rename_value "usd", to: "USD"
-#     e.comment <<~COMMENT, from: <<~COMMENT
-#       Supported currencies
-#     COMMENT
-#       Currencies
-#     COMMENT
+# @!parse
+#   class ActiveRecord::Migration
+#     # Modify an enumerated type
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the type
+#     # @yield [e] the block with the type's definition
+#     # @yieldparam Object receiver of methods specifying the type
+#     # @return [void]
+#     #
+#     # The operation can be used to rename or add values to the
+#     # enumerated type. The commend can be changed as well.
+#     #
+#     # ```ruby
+#     # change_enum "currencies" do |e|
+#     #   e.add_value "EUR", after: "BTC"
+#     #   e.add_value "GBP", before: "usd"
+#     #   e.add_value "JPY" # to the end of the list
+#     #   e.rename_value "usd", to: "USD"
+#     #   e.comment <<~COMMENT, from: <<~COMMENT
+#     #     Supported currencies
+#     #   COMMENT
+#     #     Currencies
+#     #   COMMENT
+#     # end
+#     # ```
+#     #
+#     # Please, keep in mind that all values will be added before
+#     # the first rename. That's why you should use old values
+#     # (like the `usd` instead of the `USD` in the example above)
+#     # in `before` and `after` options.
+#     #
+#     # Also notice that PostgreSQL doesn't support value deletion,
+#     # that's why adding any value makes the migration irreversible.
+#     #
+#     # It is also irreversible if you changed the comment, but
+#     # not defined its previous value.
+#     def change_enum(name, &block); end
 #   end
-#
-# Please, keep in mind that all values will be added before
-# the first rename. That's why you should use old values
-# (like the `usd` instead of the `USD` in the example above)
-# in `before` and `after` options.
-#
-# Also notice that PostgreSQL doesn't support value deletion,
-# that's why adding any value makes the migration irreversible.
-#
-# It is also irreversible if you changed the comment, but
-# not defined its previous value.
-
 module PGTrunk::Operations::Enums
   # @private
   class ChangeEnum < Base

data/lib/pg_trunk/operations/enums/create_enum.rb

@@ -1,26 +1,29 @@
 # frozen_string_literal: false
 
-# @!method ActiveRecord::Migration#create_enum(name, **options, &block)
-# Create an enumerated type by qualified name
-#
-# @param [#to_s] name (nil) The qualified name of the type
-# @option [Array<#to_s>] :values ([]) The list of values
-# @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
-#
-# @example
-#
-#   create_enum "finances.currency" do |e|
-#     e.values "BTC", "EUR", "GBP", "USD"
-#     e.value "JPY" # the alternative way to add a value to the tail
-#     e.comment <<~COMMENT
-#       The list of values for supported currencies.
-#     COMMENT
+# @!parse
+#   class ActiveRecord::Migration
+#     # Create an enumerated type by qualified name
+#     #
+#     # @param [#to_s] name (nil) The qualified name of the type
+#     # @option options [Array<#to_s>] :values ([]) The list of values
+#     # @option options [#to_s] :comment (nil) The comment describing the constraint
+#     # @yield [e] the block with the type's definition
+#     # @yieldparam Object receiver of methods specifying the type
+#     # @return [void]
+#     #
+#     # ```ruby
+#     # create_enum "finances.currency" do |e|
+#     #   e.values "BTC", "EUR", "GBP", "USD"
+#     #   e.value "JPY" # the alternative way to add a value to the tail
+#     #   e.comment <<~COMMENT
+#     #     The list of values for supported currencies.
+#     #   COMMENT
+#     # end
+#     # ```
+#     #
+#     # It is always reversible.
+#     def create_enum(name, **options, &block); end
 #   end
-#
-# It is always reversible.
-
 module PGTrunk::Operations::Enums
   # @private
   class CreateEnum < Base