docscribe 1.4.1 → 1.5.0

data/lib/docscribe/infer.rb

@@ -31,7 +31,7 @@ module Docscribe
     class << self
       # Infer exception classes raised or rescued within an AST node.
       #
-      # @param [Parser::AST::Node] node
+      # @param [Parser::AST::Node] node constant AST node to resolve
       # @return [Array<String>]
       def infer_raises_from_node(node)
         Raises.infer_raises_from_node(node)
@@ -47,9 +47,9 @@ module Docscribe
       # - trailing `:` for keyword args
       #
       # @param [String] name internal parameter name representation
-      # @param [String, nil] default_str source for the default expression
-      # @param [String] fallback_type
-      # @param [Boolean] treat_options_keyword_as_hash
+      # @param [String?] default_str source for the default expression
+      # @param [String] fallback_type default type when uncertain
+      # @param [Boolean] treat_options_keyword_as_hash treat options: as Hash
       # @return [String]
       def infer_param_type(name, default_str, fallback_type: FALLBACK_TYPE, treat_options_keyword_as_hash: true)
         Params.infer_param_type(
@@ -62,7 +62,7 @@ module Docscribe
 
       # Parse a standalone expression source string for inference helpers.
       #
-      # @param [String, nil] src
+      # @param [String?] src expression source to parse
       # @return [Parser::AST::Node, nil]
       def parse_expr(src)
         Params.parse_expr(src)
@@ -70,7 +70,7 @@ module Docscribe
 
       # Infer a return type from full method source.
       #
-      # @param [String, nil] method_source
+      # @param [String?] method_source method definition source
       # @return [String]
       def infer_return_type(method_source)
         Returns.infer_return_type(method_source)
@@ -78,7 +78,7 @@ module Docscribe
 
       # Infer a return type from an already parsed `:def` / `:defs` node.
       #
-      # @param [Parser::AST::Node] node
+      # @param [Parser::AST::Node] node constant AST node to resolve
       # @return [String]
       def infer_return_type_from_node(node)
         Returns.infer_return_type_from_node(node)
@@ -90,12 +90,12 @@ module Docscribe
       # - `:normal` => the normal return type
       # - `:rescues` => rescue-branch conditional return info
       #
-      # @param [Parser::AST::Node] node
-      # @param [String] fallback_type
-      # @param [Boolean] nil_as_optional
-      # @param [nil] core_rbs_provider Param documentation.
-      # @param [nil] param_types Param documentation.
-      # @return [Hash]
+      # @param [Parser::AST::Node] node constant AST node to resolve
+      # @param [String] fallback_type default type when uncertain
+      # @param [Boolean] nil_as_optional render nil as optional
+      # @param [Docscribe::Types::RBS::Provider?] core_rbs_provider core RBS type lookup provider
+      # @param [Hash<String, String>?] param_types parameter name -> type map
+      # @return [Hash<Symbol, String, Array<(Array<String>, String)>>]
       def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true, core_rbs_provider: nil,
                                  param_types: nil)
         Returns.returns_spec_from_node(
@@ -109,9 +109,9 @@ module Docscribe
 
       # Infer the type of the last expression in an AST node.
       #
-      # @param [Parser::AST::Node, nil] node
-      # @param [String] fallback_type
-      # @param [Boolean] nil_as_optional
+      # @param [Parser::AST::Node, nil] node constant AST node to resolve
+      # @param [String] fallback_type default type when uncertain
+      # @param [Boolean] nil_as_optional render nil as optional
       # @return [String, nil]
       def last_expr_type(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true)
         Returns.last_expr_type(
@@ -123,16 +123,16 @@ module Docscribe
 
       # Convert a constant AST node into its fully qualified name.
       #
-      # @param [Parser::AST::Node, nil] n
+      # @param [Parser::AST::Node, nil] node constant AST node to resolve
       # @return [String, nil]
-      def const_full_name(n)
-        Names.const_full_name(n)
+      def const_full_name(node)
+        Names.const_full_name(node)
       end
 
       # Infer a YARD-ish type string from a literal AST node.
       #
-      # @param [Parser::AST::Node, nil] node
-      # @param [String] fallback_type
+      # @param [Parser::AST::Node, nil] node constant AST node to resolve
+      # @param [String] fallback_type default type when uncertain
       # @return [String]
       def type_from_literal(node, fallback_type: FALLBACK_TYPE)
         Literals.type_from_literal(node, fallback_type: fallback_type)
@@ -140,15 +140,15 @@ module Docscribe
 
       # Unify two inferred type strings conservatively.
       #
-      # @param [String, nil] a
-      # @param [String, nil] b
-      # @param [String] fallback_type
-      # @param [Boolean] nil_as_optional
+      # @param [String, nil] type_a first type to unify
+      # @param [String, nil] type_b second type to unify
+      # @param [String] fallback_type default type when uncertain
+      # @param [Boolean] nil_as_optional render nil as optional
       # @return [String]
-      def unify_types(a, b, fallback_type: FALLBACK_TYPE, nil_as_optional: true)
+      def unify_types(type_a, type_b, fallback_type: FALLBACK_TYPE, nil_as_optional: true)
         Returns.unify_types(
-          a,
-          b,
+          type_a,
+          type_b,
           fallback_type: fallback_type,
           nil_as_optional: nil_as_optional
         )