From 2019869430a1636c6a003ef62d4246e4d3bc5c7c Mon Sep 17 00:00:00 2001 From: Teo Ljungberg Date: Fri, 31 Oct 2025 10:26:48 +0100 Subject: [PATCH 1/2] Add YARD documentation improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add proper YARD type annotations to all public API methods - Change Fixnum → Integer (Fixnum is deprecated in modern Ruby) - Fix typo: "prescedence" → "precedence" - Add [void] return type annotations where appropriate - Fix documentation for update_trigger (was "trigger to drop", should be "trigger to update") - Improve consistency of documentation format across adapters, configuration, and statements These changes improve code documentation without changing any behavior. --- lib/fx/adapters/postgres.rb | 20 ++++++++++---------- lib/fx/configuration.rb | 4 ++-- lib/fx/statements.rb | 30 +++++++++++++++--------------- 3 files changed, 27 insertions(+), 27 deletions(-) diff --git a/lib/fx/adapters/postgres.rb b/lib/fx/adapters/postgres.rb index 8037becd..f87a6a0a 100644 --- a/lib/fx/adapters/postgres.rb +++ b/lib/fx/adapters/postgres.rb @@ -65,7 +65,7 @@ def triggers # This is typically called in a migration via # {Fx::Statements::Function#create_function}. # - # @param sql_definition The SQL schema for the function. + # @param sql_definition [String] The SQL schema for the function. # # @return [void] def create_function(sql_definition) @@ -77,7 +77,7 @@ def create_function(sql_definition) # This is typically called in a migration via # {Fx::Statements::Trigger#create_trigger}. # - # @param sql_definition The SQL schema for the trigger. + # @param sql_definition [String] The SQL schema for the trigger. # # @return [void] def create_trigger(sql_definition) @@ -89,8 +89,8 @@ def create_trigger(sql_definition) # This is typically called in a migration via # {Fx::Statements::Function#update_function}. # - # @param name The name of the function. - # @param sql_definition The SQL schema for the function. + # @param name [String, Symbol] The name of the function. + # @param sql_definition [String] The SQL schema for the function. # # @return [void] def update_function(name, sql_definition) @@ -106,9 +106,9 @@ def update_function(name, sql_definition) # This is typically called in a migration via # {Fx::Statements::Function#update_trigger}. # - # @param name The name of the trigger. - # @param on The associated table for the trigger to drop - # @param sql_definition The SQL schema for the function. + # @param name [String, Symbol] The name of the trigger. + # @param on [String, Symbol] The associated table for the trigger to update + # @param sql_definition [String] The SQL schema for the trigger. # # @return [void] def update_trigger(name, on:, sql_definition:) @@ -121,7 +121,7 @@ def update_trigger(name, on:, sql_definition:) # This is typically called in a migration via # {Fx::Statements::Function#drop_function}. # - # @param name The name of the function to drop + # @param name [String, Symbol] The name of the function to drop # # @return [void] def drop_function(name) @@ -137,8 +137,8 @@ def drop_function(name) # This is typically called in a migration via # {Fx::Statements::Trigger#drop_trigger}. # - # @param name The name of the trigger to drop - # @param on The associated table for the trigger to drop + # @param name [String, Symbol] The name of the trigger to drop + # @param on [String, Symbol] The associated table for the trigger to drop # # @return [void] def drop_trigger(name, on:) diff --git a/lib/fx/configuration.rb b/lib/fx/configuration.rb index 8862f9af..defe2459 100644 --- a/lib/fx/configuration.rb +++ b/lib/fx/configuration.rb @@ -4,7 +4,7 @@ class Configuration # The F(x) database adapter instance to use when executing SQL. # # Defaults to an instance of {Fx::Adapters::Postgres} - # @return Fx adapter + # @return [Fx::Adapters::Postgres] Fx adapter attr_accessor :database # Prioritizes the order in the schema.rb of functions before other @@ -12,7 +12,7 @@ class Configuration # in statements below, i.e.: default column values. # # Defaults to false - # @return Boolean + # @return [Boolean] Boolean attr_accessor :dump_functions_at_beginning_of_schema def initialize diff --git a/lib/fx/statements.rb b/lib/fx/statements.rb index 665d0f4b..af844bec 100644 --- a/lib/fx/statements.rb +++ b/lib/fx/statements.rb @@ -4,13 +4,13 @@ module Statements # Create a new database function. # # @param name [String, Symbol] The name of the database function. - # @param version [Fixnum] The version number of the function, used to + # @param version [Integer] The version number of the function, used to # find the definition file in `db/functions`. This defaults to `1` if # not provided. # @param sql_definition [String] The SQL query for the function schema. # If both `sql_definition` and `version` are provided, - # `sql_definition` takes prescedence. - # @return The database response from executing the create statement. + # `sql_definition` takes precedence. + # @return [void] The database response from executing the create statement. # # @example Create from `db/functions/uppercase_users_name_v02.sql` # create_function(:uppercase_users_name, version: 2) @@ -45,10 +45,10 @@ def create_function(name, options = {}) # Drop a database function by name. # # @param name [String, Symbol] The name of the database function. - # @param revert_to_version [Fixnum] Used to reverse the `drop_function` + # @param revert_to_version [Integer] Used to reverse the `drop_function` # command on `rake db:rollback`. The provided version will be passed as # the `version` argument to {#create_function}. - # @return The database response from executing the drop statement. + # @return [void] The database response from executing the drop statement. # # @example Drop a function, rolling back to version 2 on rollback # drop_function(:uppercase_users_name, revert_to_version: 2) @@ -60,13 +60,13 @@ def drop_function(name, options = {}) # Update a database function. # # @param name [String, Symbol] The name of the database function. - # @param version [Fixnum] The version number of the function, used to + # @param version [Integer] The version number of the function, used to # find the definition file in `db/functions`. This defaults to `1` if # not provided. # @param sql_definition [String] The SQL query for the function schema. # If both `sql_definition` and `version` are provided, - # `sql_definition` takes prescedence. - # @return The database response from executing the create statement. + # `sql_definition` takes precedence. + # @return [void] The database response from executing the create statement. # # @example Update function to a given version # update_function( @@ -106,13 +106,13 @@ def update_function(name, options = {}) # Create a new database trigger. # # @param name [String, Symbol] The name of the database trigger. - # @param version [Fixnum] The version number of the trigger, used to + # @param version [Integer] The version number of the trigger, used to # find the definition file in `db/triggers`. This defaults to `1` if # not provided. # @param sql_definition [String] The SQL query for the function. An error # will be raised if `sql_definition` and `version` are both set, # as they are mutually exclusive. - # @return The database response from executing the create statement. + # @return [void] The database response from executing the create statement. # # @example Create trigger from `db/triggers/uppercase_users_name_v01.sql` # create_trigger(:uppercase_users_name, version: 1) @@ -152,10 +152,10 @@ def create_trigger(name, options = {}) # @param name [String, Symbol] The name of the database trigger. # @param on [String, Symbol] The name of the table the database trigger # is associated with. - # @param revert_to_version [Fixnum] Used to reverse the `drop_trigger` + # @param revert_to_version [Integer] Used to reverse the `drop_trigger` # command on `rake db:rollback`. The provided version will be passed as # the `version` argument to {#create_trigger}. - # @return The database response from executing the drop statement. + # @return [void] The database response from executing the drop statement. # # @example Drop a trigger, rolling back to version 3 on rollback # drop_trigger(:log_inserts, on: :users, revert_to_version: 3) @@ -171,15 +171,15 @@ def drop_trigger(name, options = {}) # and `version` parameter. # # @param name [String, Symbol] The name of the database trigger. - # @param version [Fixnum] The version number of the trigger. + # @param version [Integer] The version number of the trigger. # @param on [String, Symbol] The name of the table the database trigger # is associated with. # @param sql_definition [String] The SQL query for the function. An error # will be raised if `sql_definition` and `version` are both set, # as they are mutually exclusive. - # @param revert_to_version [Fixnum] The version number to rollback to on + # @param revert_to_version [Integer] The version number to rollback to on # `rake db rollback` - # @return The database response from executing the create statement. + # @return [void] The database response from executing the create statement. # # @example Update trigger to a given version # update_trigger( From e43195cdfd3ce51f6863cda15773c91179286d04 Mon Sep 17 00:00:00 2001 From: Teo Ljungberg Date: Fri, 31 Oct 2025 10:34:20 +0100 Subject: [PATCH 2/2] CHangelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c8af5ed..fc61e909 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ changelog, see the [commits] for each version via the version links. - Ensure multi-schema dumping in Rails 8.1.0 does not dump the same objects for all schemas (#177) - Drop Rails 7.1 due to EOL (#176) +- YARD documentation improvements (#179) ## [0.9.0]