YARD documentation improvements (#179)

- Add proper YARD type annotations to all public API methods
- Change Fixnum → Integer (Fixnum is deprecated in modern Ruby)
- s/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

Author: teoljungberg

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]
 

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:)

lib/fx/configuration.rb

@@ -4,15 +4,15 @@ 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
     # statements in order to make directly schema load work when using functions
     # 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

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(