git 5.0.0.beta.2 → 5.0.0.beta.4

data/lib/git/commands/show_ref/exists.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'git/commands/base'
-require 'git/commands/show_ref'
 
 module Git
   module Commands
@@ -51,27 +50,30 @@ module Git
         # All three are valid results — callers check exitstatus to distinguish them.
         allow_exit_status 0..2
 
-        # @!method call(*, **)
+        # @overload call(ref, **options)
         #
-        #   @overload call(ref, **options)
+        #   Execute `git show-ref --exists` to check whether a ref exists
         #
-        #     Execute `git show-ref --exists` to check whether a ref exists
+        #   @param ref [String] the fully-qualified ref name to check
+        #     (e.g. `"refs/heads/main"`)
         #
-        #     @param ref [String] the fully-qualified ref name to check
-        #       (e.g. `"refs/heads/main"`)
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Numeric] :timeout (nil) abort the command after this many
+        #     seconds
         #
-        #     @option options [Numeric] :timeout (nil) abort the command after this many
-        #       seconds
+        #   @return [Git::CommandLine::Result] the result of calling
+        #     `git show-ref --exists`
         #
-        #     @return [Git::CommandLineResult] the result of calling
-        #       `git show-ref --exists`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if no ref is provided
+        #   @raise [Git::FailedError] if git exits outside the allowed range (exit code > 2)
         #
-        #     @raise [Git::FailedError] if git exits with a status outside `0..2`
+        # @api public
         #
+        def call(*, **)
+          super
+        end
       end
     end
   end

data/lib/git/commands/show_ref/list.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'git/commands/base'
-require 'git/commands/show_ref'
 
 module Git
   module Commands
@@ -19,8 +18,6 @@ module Git
       # For stdin-based filtering, use {Git::Commands::ShowRef::ExcludeExisting}.
       # For a simple boolean existence check (git >= 2.43), use {Git::Commands::ShowRef::Exists}.
       #
-      # @note `arguments` block audited against https://git-scm.com/docs/git-show-ref/2.53.0
-      #
       # @example List all refs
       #   cmd = Git::Commands::ShowRef::List.new(execution_context)
       #   result = cmd.call
@@ -38,6 +35,8 @@ module Git
       #   cmd = Git::Commands::ShowRef::List.new(execution_context)
       #   result = cmd.call('v1.0', 'v2.0', tags: true)
       #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-show-ref/2.53.0
+      #
       # @see Git::Commands::ShowRef
       #
       # @see https://git-scm.com/docs/git-show-ref
@@ -49,34 +48,34 @@ module Git
           literal 'show-ref'
 
           # Include the HEAD ref even if it would normally be filtered out
-          # @see https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---head
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---head
           flag_option :head
 
           # Dereference annotated tags; outputs an additional line per tag with
           # the de-referenced object SHA followed by `^{}`
-          # @see https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---dereference
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---dereference
           flag_option %i[dereference d]
 
           # Show only the SHA part of the ref, optionally abbreviated to <n> hex digits;
           # pass `true` for full-length SHA, or an integer for the abbreviation length
-          # @see https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---hashn
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---hashn
           flag_or_value_option %i[hash s], inline: true
 
           # Abbreviate the object names to at least <n> hex digits; pass `true` to
           # use the default abbreviation length, or an integer for an explicit length
-          # @see https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---abbrevlength
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---abbrevlength
           flag_or_value_option :abbrev, inline: true
 
           # Limit to refs under refs/heads/ only (preferred over :heads on git >= 2.46)
-          # @see https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---branches
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---branches
           flag_option :branches
 
           # Limit to refs under refs/heads/ only (deprecated synonym for :branches in git >= 2.46)
-          # @see https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---branches
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---branches
           flag_option :heads
 
           # Limit to refs under refs/tags/ only
-          # @see https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---tags
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---tags
           flag_option :tags
 
           execution_option :timeout
@@ -92,53 +91,58 @@ module Git
         # Exit status 1 means no refs matched; that is a normal (non-error) outcome
         allow_exit_status 0..1
 
-        # @!method call(*pattern, **options)
+        # @overload call(*pattern, **options)
+        #
+        #   Execute `git show-ref` to list matching refs
         #
-        #   @overload call(*pattern, **options)
+        #   @param pattern [Array<String>] zero or more patterns to filter refs
         #
-        #     Execute `git show-ref` to list matching refs
+        #     When empty, all refs are listed.
         #
-        #     @param pattern [Array<String>] zero or more patterns to filter refs
+        #   @param options [Hash] command options
         #
-        #       When empty, all refs are listed.
+        #   @option options [Boolean, nil] :head (nil) show the HEAD ref even when filtered
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, nil] :dereference (nil) dereference annotated tags,
+        #     emitting an extra line per tag whose SHA points to the tagged object
         #
-        #     @option options [Boolean, nil] :head (nil) show the HEAD ref even when filtered
+        #     Alias: `:d`
         #
-        #     @option options [Boolean, nil] :dereference (nil) dereference annotated tags,
-        #       emitting an extra line per tag whose SHA points to the tagged object
+        #   @option options [Boolean, Integer, nil] :hash (nil) show only the SHA part of each ref
         #
-        #       Alias: `:d`
+        #     Pass `true` for full-length SHAs or an integer for the abbreviation length
+        #     (e.g. `hash: 7`).
         #
-        #     @option options [Boolean, Integer, nil] :hash (nil) show only the SHA part of each ref
+        #     Alias: `:s`
         #
-        #       Pass `true` for full-length SHAs or an integer for the abbreviation length
-        #       (e.g. `hash: 7`).
+        #   @option options [Boolean, Integer, nil] :abbrev (nil) abbreviate object names
         #
-        #       Alias: `:s`
+        #     Pass `true` for the default length or an integer for a specific length.
         #
-        #     @option options [Boolean, Integer, nil] :abbrev (nil) abbreviate object names
+        #   @option options [Boolean, nil] :branches (nil) limit output to local branches (refs/heads/)
         #
-        #       Pass `true` for the default length or an integer for a specific length.
+        #     Prefer `:branches` over `:heads` on git >= 2.46; `:heads` emits the deprecated
+        #     `--heads` flag.
         #
-        #     @option options [Boolean, nil] :branches (nil) limit output to local branches (refs/heads/)
+        #   @option options [Boolean, nil] :heads (nil) limit output to refs under refs/heads/
         #
-        #       Prefer `:branches` over `:heads` on git >= 2.46; `:heads` emits the deprecated
-        #       `--heads` flag.
+        #     Deprecated at the git level in git 2.46. Use `:branches` instead.
         #
-        #     @option options [Boolean, nil] :heads (nil) limit output to refs under refs/heads/
+        #   @option options [Boolean, nil] :tags (nil) limit output to refs under refs/tags/
         #
-        #       Deprecated at the git level in git 2.46. Use `:branches` instead.
+        #   @option options [Numeric] :timeout (nil) abort the command after this many seconds
         #
-        #     @option options [Boolean, nil] :tags (nil) limit output to refs under refs/tags/
+        #   @return [Git::CommandLine::Result] the result of calling `git show-ref`
         #
-        #     @option options [Numeric] :timeout (nil) abort the command after this many seconds
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @return [Git::CommandLineResult] the result of calling `git show-ref`
+        #   @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
         #
-        #     @raise [Git::FailedError] if git exits with a status outside `0..1`
+        # @api public
         #
+        def call(*, **)
+          super
+        end
       end
     end
   end

data/lib/git/commands/show_ref/verify.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'git/commands/base'
-require 'git/commands/show_ref'
 
 module Git
   module Commands
@@ -49,19 +48,19 @@ module Git
           literal '--verify'
 
           # Suppress output; useful when you only care whether the ref exists
-          # @see https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---quiet
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---quiet
           flag_option %i[quiet q]
 
           # Dereference annotated tags; emit an extra line per tag with SHA^{}
-          # @see https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---dereference
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---dereference
           flag_option %i[dereference d]
 
           # Show only the SHA; pass `true` for full-length or an integer for abbreviated length
-          # @see https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---hashn
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---hashn
           flag_or_value_option %i[hash s], inline: true
 
           # Abbreviate object names; pass `true` for default or integer for explicit length
-          # @see https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---abbrevlength
+          # See https://git-scm.com/docs/git-show-ref#Documentation/git-show-ref.txt---abbrevlength
           flag_or_value_option :abbrev, inline: true
 
           execution_option :timeout
@@ -72,48 +71,51 @@ module Git
           operand :ref, repeatable: true, required: true
         end
 
-        # @!method call(*ref, **options)
+        # @overload call(*ref, **options)
         #
-        #   @overload call(*ref, **options)
+        #   Execute `git show-ref --verify` to verify refs by their full name
         #
-        #     Execute `git show-ref --verify` to verify refs by their full name
+        #   @param ref [Array<String>] one or more fully-qualified ref names
         #
-        #     @param ref [Array<String>] one or more fully-qualified ref names
+        #     Each name must begin with `refs/` (or be `HEAD`). At least one is required.
         #
-        #       Each name must begin with `refs/` (or be `HEAD`). At least one is required.
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, nil] :quiet (nil) suppress all output
         #
-        #     @option options [Boolean, nil] :quiet (nil) suppress all output
+        #     Useful when you only care whether the ref exists.
         #
-        #       Useful when you only care whether the ref exists.
+        #     Alias: `:q`
         #
-        #       Alias: `:q`
+        #   @option options [Boolean, nil] :dereference (nil) dereference annotated tags,
+        #     emitting an extra `^{}` line per tag
         #
-        #     @option options [Boolean, nil] :dereference (nil) dereference annotated tags,
-        #       emitting an extra `^{}` line per tag
+        #     Alias: `:d`
         #
-        #       Alias: `:d`
+        #   @option options [Boolean, Integer, nil] :hash (nil) show only the SHA part
         #
-        #     @option options [Boolean, Integer, nil] :hash (nil) show only the SHA part
+        #     Pass `true` for full-length SHAs or an integer for abbreviation length.
         #
-        #       Pass `true` for full-length SHAs or an integer for abbreviation length.
+        #     Alias: `:s`
         #
-        #       Alias: `:s`
+        #   @option options [Boolean, Integer, nil] :abbrev (nil) abbreviate object names
         #
-        #     @option options [Boolean, Integer, nil] :abbrev (nil) abbreviate object names
+        #     Pass `true` for the default length or an integer for a specific length.
         #
-        #       Pass `true` for the default length or an integer for a specific length.
+        #   @option options [Numeric] :timeout (nil) abort the command after this many
+        #     seconds
         #
-        #     @option options [Numeric] :timeout (nil) abort the command after this many
-        #       seconds
+        #   @return [Git::CommandLine::Result] the result of calling `git show-ref --verify`
         #
-        #     @return [Git::CommandLineResult] the result of calling `git show-ref --verify`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if no ref names are provided
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::FailedError] if any ref cannot be resolved (exit status 1)
+        # @api public
         #
+        def call(*, **)
+          super
+        end
       end
     end
   end

data/lib/git/commands/show_ref.rb

@@ -21,10 +21,6 @@ module Git
     # - {ShowRef::Exists} — boolean existence check without output (git >= 2.43)
     #   (`git show-ref --exists <ref>`)
     #
-    # @api private
-    #
-    # @see https://git-scm.com/docs/git-show-ref git-show-ref documentation
-    #
     # @example List all refs matching a pattern
     #   cmd = Git::Commands::ShowRef::List.new(execution_context)
     #   result = cmd.call('refs/tags/', tags: true)
@@ -36,6 +32,10 @@ module Git
     #   result = cmd.call('refs/heads/main')
     #   result.stdout  # => "abc1234 refs/heads/main\n"
     #
+    # @see https://git-scm.com/docs/git-show-ref git-show-ref documentation
+    #
+    # @api private
+    #
     module ShowRef
     end
   end

data/lib/git/commands/stash/apply.rb

@@ -10,14 +10,6 @@ module Git
       # Applies the changes recorded in a stash to the working tree.
       # Unlike {Pop}, this does not remove the stash from the stash list.
       #
-      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
-      #
-      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
-      #
-      # @see https://git-scm.com/docs/git-stash git-stash documentation
-      #
-      # @api private
-      #
       # @example Apply the latest stash
       #   Git::Commands::Stash::Apply.new(execution_context).call
       #
@@ -27,6 +19,14 @@ module Git
       # @example Apply and restore index state
       #   Git::Commands::Stash::Apply.new(execution_context).call(index: true)
       #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
       class Apply < Git::Commands::Base
         arguments do
           literal 'stash'
@@ -36,39 +36,45 @@ module Git
           operand :stash
         end
 
-        # @!method call(*, **)
+        # @overload call(**options)
+        #
+        #   Apply the latest stash
         #
-        #   Apply stashed changes
+        #   @param options [Hash] command options
         #
-        #   @overload call(**options)
+        #   @option options [Boolean, nil] :index (nil) restore the index state as well
         #
-        #     Apply the latest stash
+        #   @option options [Boolean, nil] :quiet (nil) suppress informational messages
         #
-        #     @param options [Hash] command options
+        #     Alias: :q
         #
-        #     @option options [Boolean, nil] :index (nil) restore the index state as well
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        # @overload call(stash, **options)
         #
-        #       Alias: :q
+        #   Apply a specific stash
         #
-        #   @overload call(stash, **options)
+        #   @param stash [String] stash reference (e.g., 'stash@\\{0}', '0')
         #
-        #     Apply a specific stash
+        #   @param options [Hash] command options
         #
-        #     @param stash [String] stash reference (e.g., 'stash@\\{0}', '0')
+        #   @option options [Boolean, nil] :index (nil) restore the index state as well
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, nil] :quiet (nil) suppress informational messages
         #
-        #     @option options [Boolean, nil] :index (nil) restore the index state as well
+        #     Alias: :q
         #
-        #     @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #       Alias: :q
+        # @return [Git::CommandLine::Result] the result of calling `git stash apply`
         #
-        #   @return [Git::CommandLineResult] the result of calling `git stash apply`
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #   @raise [Git::FailedError] if the stash does not exist
+        # @api public
+        #
+        def call(*, **)
+          super
+        end
       end
     end
   end

data/lib/git/commands/stash/branch.rb

@@ -16,6 +16,12 @@ module Git
       # be created at the commit that was HEAD when the stash was created, so
       # applying the stash should succeed.
       #
+      # @example Create branch from latest stash
+      #   Git::Commands::Stash::Branch.new(execution_context).call('my-branch')
+      #
+      # @example Create branch from specific stash
+      #   Git::Commands::Stash::Branch.new(execution_context).call('my-branch', 'stash@{2}')
+      #
       # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
       #
       # @see Git::Commands::Stash Git::Commands::Stash for usage examples
@@ -24,12 +30,6 @@ module Git
       #
       # @api private
       #
-      # @example Create branch from latest stash
-      #   Git::Commands::Stash::Branch.new(execution_context).call('my-branch')
-      #
-      # @example Create branch from specific stash
-      #   Git::Commands::Stash::Branch.new(execution_context).call('my-branch', 'stash@{2}')
-      #
       class Branch < Git::Commands::Base
         arguments do
           literal 'stash'
@@ -38,7 +38,7 @@ module Git
           operand :stash
         end
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
         #   Create a branch from a stash entry
         #
@@ -56,9 +56,11 @@ module Git
         #
         #     @param stash [String] stash reference (e.g., 'stash@\\{0}', '0')
         #
-        #   @return [Git::CommandLineResult] the result of calling `git stash branch`
+        #   @return [Git::CommandLine::Result] the result of calling `git stash branch`
         #
         #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
       end
     end
   end

data/lib/git/commands/stash/clear.rb

@@ -9,6 +9,9 @@ module Git
       #
       # Removes all stash entries. Use with caution as this cannot be undone.
       #
+      # @example Clear all stashes
+      #   Git::Commands::Stash::Clear.new(execution_context).call
+      #
       # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
       #
       # @see Git::Commands::Stash Git::Commands::Stash for usage examples
@@ -17,24 +20,23 @@ module Git
       #
       # @api private
       #
-      # @example Clear all stashes
-      #   Git::Commands::Stash::Clear.new(execution_context).call
-      #
       class Clear < Git::Commands::Base
         arguments do
           literal 'stash'
           literal 'clear'
         end
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
         #   @overload call()
         #
         #     Clear all stash entries
         #
-        #   @return [Git::CommandLineResult] the result of calling `git stash clear`
+        #   @return [Git::CommandLine::Result] the result of calling `git stash clear`
         #
         #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
       end
     end
   end

data/lib/git/commands/stash/create.rb

@@ -14,6 +14,12 @@ module Git
       # The command creates a stash commit and outputs its SHA, but does not
       # update refs/stash. Use {Store} to store the commit in the stash reflog.
       #
+      # @example Create a stash commit
+      #   Git::Commands::Stash::Create.new(execution_context).call
+      #
+      # @example Create a stash commit with a message
+      #   Git::Commands::Stash::Create.new(execution_context).call('WIP: my changes')
+      #
       # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
       #
       # @see Git::Commands::Stash Git::Commands::Stash for usage examples
@@ -22,12 +28,6 @@ module Git
       #
       # @api private
       #
-      # @example Create a stash commit
-      #   Git::Commands::Stash::Create.new(execution_context).call
-      #
-      # @example Create a stash commit with a message
-      #   Git::Commands::Stash::Create.new(execution_context).call('WIP: my changes')
-      #
       class Create < Git::Commands::Base
         arguments do
           literal 'stash'
@@ -35,7 +35,7 @@ module Git
           operand :message
         end
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
         #   Create a stash commit
         #
@@ -49,9 +49,11 @@ module Git
         #
         #     @param message [String] optional message for the stash commit
         #
-        #   @return [Git::CommandLineResult] the result of calling `git stash create`
+        #   @return [Git::CommandLine::Result] the result of calling `git stash create`
         #
         #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
       end
     end
   end

data/lib/git/commands/stash/drop.rb

@@ -10,6 +10,12 @@ module Git
       # Removes a single stash entry from the list of stash entries.
       # If no stash reference is given, it removes the latest one.
       #
+      # @example Drop the latest stash
+      #   Git::Commands::Stash::Drop.new(execution_context).call
+      #
+      # @example Drop a specific stash
+      #   Git::Commands::Stash::Drop.new(execution_context).call('stash@\\{2}')
+      #
       # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
       #
       # @see Git::Commands::Stash Git::Commands::Stash for usage examples
@@ -18,12 +24,6 @@ module Git
       #
       # @api private
       #
-      # @example Drop the latest stash
-      #   Git::Commands::Stash::Drop.new(execution_context).call
-      #
-      # @example Drop a specific stash
-      #   Git::Commands::Stash::Drop.new(execution_context).call('stash@\\{2}')
-      #
       class Drop < Git::Commands::Base
         arguments do
           literal 'stash'
@@ -32,7 +32,7 @@ module Git
           operand :stash
         end
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
         #   Drop a stash entry
         #
@@ -46,6 +46,8 @@ module Git
         #
         #       Alias: :q
         #
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
         #   @overload call(stash, **options)
         #
         #     Drop a specific stash
@@ -58,9 +60,13 @@ module Git
         #
         #       Alias: :q
         #
-        #   @return [Git::CommandLineResult] the result of calling `git stash drop`
+        #     @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @return [Git::CommandLine::Result] the result of calling `git stash drop`
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #   @raise [Git::FailedError] if the stash does not exist
+        #   @api public
       end
     end
   end

data/lib/git/commands/stash/list.rb

@@ -8,6 +8,9 @@ module Git
     module Stash
       # List all stash entries
       #
+      # @example List all stashes
+      #   Git::Commands::Stash::List.new(execution_context).call
+      #
       # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
       #
       # @see Git::Commands::Stash Git::Commands::Stash for usage examples
@@ -16,9 +19,6 @@ module Git
       #
       # @api private
       #
-      # @example List all stashes
-      #   Git::Commands::Stash::List.new(execution_context).call
-      #
       class List < Git::Commands::Base
         arguments do
           literal 'stash'
@@ -26,13 +26,17 @@ module Git
           literal "--format=#{Git::Parsers::Stash::STASH_FORMAT}"
         end
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
         #   List all stash entries
         #
         #   @overload call()
         #
-        #     @return [Git::CommandLineResult] the result of calling `git stash list`
+        #     @return [Git::CommandLine::Result] the result of calling `git stash list`
+        #
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #     @api public
       end
     end
   end