graphql 2.6.11 → 2.6.13

data/lib/graphql/schema/member/has_dataloader.rb

@@ -1,21 +1,32 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
     class Member
-      # @api public
-      # Shared methods for working with {Dataloader} inside GraphQL runtime objects.
+      # **API:** public Shared methods for working with [Dataloader](rdoc-ref:Dataloader) inside GraphQL runtime objects.
       module HasDataloader
-        # @return [GraphQL::Dataloader] The dataloader for the currently-running query
+        # **Returns**
+        #
+        # - `GraphQL::Dataloader` — The dataloader for the currently-running query
+        #
+        # :call-seq:
+        #   dataloader() -> GraphQL::Dataloader
         def dataloader
           context.dataloader
         end
 
         # A shortcut method for loading a key from a source.
         # Identical to `dataloader.with(source_class, *source_args).load(load_key)`
-        # @param source_class [Class<GraphQL::Dataloader::Source>]
-        # @param source_args [Array<Object>] Any extra parameters defined in `source_class`'s `initialize` method
-        # @param load_key [Object] The key to look up using `def fetch`
+        #
+        # **Parameters**
+        #
+        # - `source_class` (`Class<GraphQL::Dataloader::Source>`)
+        # - `source_args` (`Array<Object>`) — Any extra parameters defined in `source_class`'s `initialize` method
+        # - `load_key` (`Object`) — The key to look up using `def fetch`
+        #
+        # :call-seq:
+        #   dataload(Class[GraphQL::Dataloader::Source] source_class, Array[Object] *source_args, Object load_key)
         def dataload(source_class, *source_args, load_key)
           dataloader.with(source_class, *source_args).load(load_key)
         end
@@ -23,29 +34,56 @@ module GraphQL
         # A shortcut method for loading many keys from a source.
         # Identical to `dataloader.with(source_class, *source_args).load_all(load_keys)`
         #
-        # @example
-        #   field :score, Integer, resolve_batch: true
+        # **Examples**
+        #
+        # **Example: field :score, Integer, resolve_batch: true**
+        #
+        # ```ruby
+        # def self.score(posts)
+        #   dataload_all(PostScoreSource, posts.map(&:id))
+        # end
+        # ```
         #
-        #   def self.score(posts)
-        #     dataload_all(PostScoreSource, posts.map(&:id))
-        #   end
+        # **Parameters**
         #
-        # @param source_class [Class<GraphQL::Dataloader::Source>]
-        # @param source_args [Array<Object>] Any extra parameters defined in `source_class`'s `initialize` method
-        # @param load_keys [Array<Object>] The keys to look up using `def fetch`
+        # - `source_class` (`Class<GraphQL::Dataloader::Source>`)
+        # - `source_args` (`Array<Object>`) — Any extra parameters defined in `source_class`'s `initialize` method
+        # - `load_keys` (`Array<Object>`) — The keys to look up using `def fetch`
+        #
+        # :call-seq:
+        #   dataload_all(Class[GraphQL::Dataloader::Source] source_class, Array[Object] *source_args, Array[Object] load_keys)
         def dataload_all(source_class, *source_args, load_keys)
           dataloader.with(source_class, *source_args).load_all(load_keys)
         end
 
-        # Find an object with ActiveRecord via {Dataloader::ActiveRecordSource}.
-        # @param model [Class<ActiveRecord::Base>]
-        # @param find_by_value [Object] Usually an `id`, might be another value if `find_by:` is also provided
-        # @param find_by [Symbol, String] A column name to look the record up by. (Defaults to the model's primary key.)
-        # @return [ActiveRecord::Base, nil]
-        # @example Finding a record by ID
-        #   dataload_record(Post, 5) # Like `Post.find(5)`, but dataloaded
-        # @example Finding a record by another attribute
-        #   dataload_record(User, "matz", find_by: :handle) # Like `User.find_by(handle: "matz")`, but dataloaded
+        # Find an object with ActiveRecord via [Dataloader::ActiveRecordSource](rdoc-ref:Dataloader::ActiveRecordSource).
+        #
+        # **Parameters**
+        #
+        # - `model` (`Class<ActiveRecord::Base>`)
+        # - `find_by_value` (`Object`) — Usually an `id`, might be another value if `find_by:` is also provided
+        # - `find_by` (`Symbol, String`) — A column name to look the record up by. (Defaults to the model's primary key.)
+        #
+        # **Returns**
+        #
+        # - `ActiveRecord::Base, nil`
+        #
+        # **Examples**
+        #
+        # **Example: Finding a record by ID**
+        #
+        # ```ruby
+        # dataload_record(Post, 5) # Like `Post.find(5)`, but dataloaded
+        # ```
+        #
+        # **Example: Finding a record by another attribute**
+        #
+        # ```ruby
+        # dataload_record(User, "matz", find_by: :handle) # Like `User.find_by(handle: "matz")`, but dataloaded
+        # ```
+        #
+        # :call-seq:
+        #   dataload_record(Class[ActiveRecord::Base] model, Object find_by_value, Symbol | String find_by:) -> ActiveRecord::Base | nil
         def dataload_record(model, find_by_value, find_by: nil)
           source = if find_by
             dataloader.with(Dataloader::ActiveRecordSource, model, find_by: find_by)
@@ -56,7 +94,7 @@ module GraphQL
           source.load(find_by_value)
         end
 
-        # @see dataload_record Like `dataload_record`, but accepts an Array of `find_by_values`
+        # See [dataload_record](rdoc-ref:dataload_record) Like `dataload_record`, but accepts an Array of `find_by_values`
         def dataload_all_records(model, find_by_values, find_by: nil)
           source = if find_by
             dataloader.with(Dataloader::ActiveRecordSource, model, find_by: find_by)
@@ -66,15 +104,34 @@ module GraphQL
           source.load_all(find_by_values)
         end
 
-        # Look up an associated record using a Rails association (via {Dataloader::ActiveRecordAssociationSource})
-        # @param association_name [Symbol] A `belongs_to` or `has_one` association. (If a `has_many` association is named here, it will be selected without pagination.)
-        # @param record [ActiveRecord::Base] The object that the association belongs to.
-        # @param scope [ActiveRecord::Relation] A scope to look up the associated record in
-        # @return [ActiveRecord::Base, nil] The associated record, if there is one
-        # @example Looking up a belongs_to on the current object
-        #    dataload_association(:parent) # Equivalent to `object.parent`, but dataloaded
-        # @example Looking up an associated record on some other object
-        #    dataload_association(comment, :post) # Equivalent to `comment.post`, but dataloaded
+        # Look up an associated record using a Rails association (via [Dataloader::ActiveRecordAssociationSource](rdoc-ref:Dataloader::ActiveRecordAssociationSource))
+        #
+        # **Parameters**
+        #
+        # - `association_name` (`Symbol`) — A `belongs_to` or `has_one` association. (If a `has_many` association is named here, it will be selected without pagination.)
+        # - `record` (`ActiveRecord::Base`) — The object that the association belongs to.
+        # - `scope` (`ActiveRecord::Relation`) — A scope to look up the associated record in
+        #
+        # **Returns**
+        #
+        # - `ActiveRecord::Base, nil` — The associated record, if there is one
+        #
+        # **Examples**
+        #
+        # **Example: Looking up a belongs_to on the current object**
+        #
+        # ```ruby
+        # dataload_association(:parent) # Equivalent to `object.parent`, but dataloaded
+        # ```
+        #
+        # **Example: Looking up an associated record on some other object**
+        #
+        # ```ruby
+        # dataload_association(comment, :post) # Equivalent to `comment.post`, but dataloaded
+        # ```
+        #
+        # :call-seq:
+        #   dataload_association(ActiveRecord::Base record, Symbol association_name, ActiveRecord::Relation scope:) -> ActiveRecord::Base | nil
         def dataload_association(record = object, association_name, scope: nil)
           source = if scope
             dataloader.with(Dataloader::ActiveRecordAssociationSource, association_name, scope)
@@ -84,7 +141,7 @@ module GraphQL
           source.load(record)
         end
 
-        # @see dataload_association Like `dataload_assocation` but accepts an Array of records (required param)
+        # See [dataload_association](rdoc-ref:dataload_association) Like `dataload_assocation` but accepts an Array of records (required param)
         def dataload_all_associations(records, association_name, scope: nil)
           source = if scope
             dataloader.with(Dataloader::ActiveRecordAssociationSource, association_name, scope)

data/lib/graphql/schema/member/has_deprecation_reason.rb

@@ -1,14 +1,25 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
     class Member
+      #--
+      # @requires_ancestor: GraphQL::Schema::Member::HasDirectives
       module HasDeprecationReason
-        # @return [String, nil] Explains why this member was deprecated (if present, this will be marked deprecated in introspection)
+        # **Returns**
+        #
+        # - `String, nil` — Explains why this member was deprecated (if present, this will be marked deprecated in introspection)
         attr_reader :deprecation_reason
 
         # Set the deprecation reason for this member, or remove it by assigning `nil`
-        # @param text [String, nil]
+        #
+        # **Parameters**
+        #
+        # - `text` (`String, nil`)
+        #
+        # :call-seq:
+        #   deprecation_reason=(String | nil text)
         def deprecation_reason=(text)
           @deprecation_reason = text
           if text.nil?
@@ -24,6 +35,8 @@ module GraphQL
           child_class.extend(ClassMethods)
         end
 
+        #--
+        # @requires_ancestor: GraphQL::Schema::Member::HasDeprecationReason
         module ClassMethods
           def deprecation_reason(new_reason = NOT_CONFIGURED)
             if NOT_CONFIGURED.equal?(new_reason)

data/lib/graphql/schema/member/has_directives.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Schema
@@ -6,7 +7,10 @@ module GraphQL
       module HasDirectives
         def self.extended(child_cls)
           super
-          child_cls.module_exec { self.own_directives = nil }
+          child_cls.module_exec {
+            #: self as GraphQL::Schema::Member::HasDirectives
+            self.own_directives = nil
+          }
         end
 
         def inherited(child_cls)
@@ -18,7 +22,12 @@ module GraphQL
         #
         # It removes a previously-attached instance of `dir_class`, if there is one.
         #
-        # @return [void]
+        # **Returns**
+        #
+        # - `void`
+        #
+        # :call-seq:
+        #   directive(dir_class, **options) -> void
         def directive(dir_class, **options)
           @own_directives ||= []
           HasDirectives.add_directive(self, @own_directives, dir_class, options)
@@ -26,8 +35,17 @@ module GraphQL
         end
 
         # Remove an attached instance of `dir_class`, if there is one
-        # @param dir_class [Class<GraphQL::Schema::Directive>]
-        # @return [viod]
+        #
+        # **Parameters**
+        #
+        # - `dir_class` (`Class<GraphQL::Schema::Directive>`)
+        #
+        # **Returns**
+        #
+        # - `void`
+        #
+        # :call-seq:
+        #   remove_directive(Class[GraphQL::Schema::Directive] dir_class) -> void
         def remove_directive(dir_class)
           HasDirectives.remove_directive(@own_directives, dir_class)
           nil
@@ -56,7 +74,7 @@ module GraphQL
                 GraphQL::EmptyObjects::EMPTY_ARRAY
               end
               if !inherited_directives.empty? && directives
-                dirs = []
+                dirs = [] #: Array[GraphQL::Schema::Directive]?
                 merge_directives(dirs, inherited_directives)
                 merge_directives(dirs, directives)
                 dirs
@@ -68,8 +86,9 @@ module GraphQL
                 GraphQL::EmptyObjects::EMPTY_ARRAY
               end
             when Module
-              dirs = nil
-              schema_member.ancestors.reverse_each do |ancestor|
+              dirs = nil #: Array[GraphQL::Schema::Directive]?
+              ancestors = schema_member.ancestors #: Array[untyped]
+              ancestors.reverse_each do |ancestor|
                 if ancestor.respond_to?(:own_directives) &&
                     !(anc_dirs = ancestor.own_directives).empty?
                   dirs ||= []
@@ -93,9 +112,18 @@ module GraphQL
           # Modify `target` by adding items from `dirs` such that:
           # - Any name conflict is overridden by the incoming member of `dirs`
           # - Any other member of `dirs` is appended
-          # @param target [Array<GraphQL::Schema::Directive>]
-          # @param dirs [Array<GraphQL::Schema::Directive>]
-          # @return [void]
+          #
+          # **Parameters**
+          #
+          # - `target` (`Array<GraphQL::Schema::Directive>`)
+          # - `dirs` (`Array<GraphQL::Schema::Directive>`)
+          #
+          # **Returns**
+          #
+          # - `void`
+          #
+          # :call-seq:
+          #   merge_directives(Array[GraphQL::Schema::Directive] target, Array[GraphQL::Schema::Directive] dirs) -> void
           def merge_directives(target, dirs)
             dirs.each do |dir|
               if (idx = target.find_index { |d| d.graphql_name == dir.graphql_name })