add: add yardoc to results

Author: MarieGiy

lib/hati_command/failure.rb

@@ -1,43 +1,94 @@
 # frozen_string_literal: true
 
+# @module HatiCommand
+# Provides command handling functionalities and result objects.
 module HatiCommand
- # This class represents a failure result.
+ # @class Failure
+ # Represents a failure result in the Result pattern.
+ # This class is used to wrap failure values and provide a consistent interface
+ # for handling both successful and failed operations.
  #
- # @example
- # failure_result = HatiCommand::Failure.new("An error occurred")
- # failure_result.failure # => "An error occurred"
- # failure_result.failure? # => true
- # failure_result.success # => nil
- # failure_result.success? # => false
+ # The Failure class is part of the Result pattern implementation, working alongside
+ # the Success class to provide a type-safe way to handle operation outcomes.
+ #
+ # @example Basic usage
+ # failure = HatiCommand::Failure.new("Operation failed")
+ # failure.failure? # => true
+ # failure.success? # => false
+ #
+ # @example With error and metadata
+ # error = StandardError.new("Database connection failed")
+ # failure = HatiCommand::Failure.new(
+ # "Could not save record",
+ # err: error,
+ # meta: { attempted_at: Time.now }
+ # )
+ #
+ # @example Pattern matching
+ # case result
+ # when HatiCommand::Failure
+ # handle_error(result.failure)
+ # end
+ #
+ # @see HatiCommand::Success
+ # @see HatiCommand::Result
  class Failure < Result
- # Returns the value associated with the failure.
+ # Returns the failure value wrapped by this Failure instance.
+ # This method provides access to the actual error value or message
+ # that describes why the operation failed.
  #
- # @return [Object] the value of the failure
+ # @return [Object] The wrapped failure value
+ # @example
+ # failure = Failure.new("Database error")
+ # failure.failure # => "Database error"
  def failure
  value
  end
 
- # Indicates whether the result is a failure.
+ # Indicates that this is a failure result.
+ # This method is part of the Result pattern interface and always
+ # returns true for Failure instances.
  #
- # @return [Boolean] true if this is a failure, false otherwise
+ # @return [Boolean] Always returns true
+ # @example
+ # failure = Failure.new("Error")
+ # failure.failure? # => true
  def failure?
  true
  end
 
- # Returns nil as there is no success value in a failure.
+ # Returns nil since a Failure has no success value.
+ # This method is part of the Result pattern interface and always
+ # returns nil for Failure instances.
  #
- # @return [nil]
+ # @return [nil] Always returns nil
+ # @example
+ # failure = Failure.new("Error")
+ # failure.success # => nil
  def success
  nil
  end
 
- # Indicates whether the result is a success.
+ # Indicates that this is not a success result.
+ # This method is part of the Result pattern interface and always
+ # returns false for Failure instances.
  #
- # @return [Boolean] false since this is a failure
+ # @return [Boolean] Always returns false
+ # @example
+ # failure = Failure.new("Error")
+ # failure.success? # => false
  def success?
  false
  end
 
+ # Returns the symbolic representation of this result type.
+ # Useful for pattern matching and result type checking.
+ #
+ # @return [Symbol] Always returns :failure
+ # @api public
+ # @example
+ # failure = Failure.new("Error")
+ # failure.to_sym # => :failure
  def to_sym
  :failure
  end

lib/hati_command/result.rb

@@ -1,54 +1,105 @@
 # frozen_string_literal: true
 
+# @module HatiCommand
+# Provides command handling functionalities and result objects.
 module HatiCommand
- # This class represents a result.
+ # @class Result
+ # Base class for the Result pattern implementation.
+ # This class serves as the foundation for Success and Failure result types,
+ # providing common functionality and a consistent interface for handling
+ # operation outcomes.
  #
- # @example
- # result = HatiCommand::Result.new("Success", err: nil, meta: { key: "value" })
- # result.value # => "Success"
- # result.error # => nil
- # result.meta # => { key: "value" }
+ # The Result pattern helps in handling operation outcomes in a type-safe way,
+ # making it explicit whether an operation succeeded or failed, and carrying
+ # additional context like error messages and metadata.
  #
- # @!attribute [r] value
- # @return [Object] the value associated with the result
+ # @abstract Subclass and override {#to_sym} to implement a concrete result type
+ #
+ # @example Basic usage
+ # result = HatiCommand::Result.new("Operation output")
+ # result.value # => "Operation output"
+ #
+ # @example With error and metadata
+ # result = HatiCommand::Result.new(
+ # "Operation output",
+ # err: "Warning: partial completion",
+ # meta: { duration_ms: 150 }
+ # )
+ #
+ # @example Using trace information
+ # result = HatiCommand::Result.new("Output", trace: caller(1..1))
+ # result.trace # => ["path/to/file.rb:42:in `method_name'"]
+ #
+ # @see HatiCommand::Success
+ # @see HatiCommand::Failure
  #
- # @!attribute [r] err
- # @return [String, nil] an optional error message associated with the result
+ # @!attribute [r] value
+ # @return [Object] The wrapped value representing the operation's output
  #
  # @!attribute [r] meta
- # @return [Hash] optional metadata associated with the result
+ # @return [Hash] Additional metadata associated with the result
+ #
+ # @!attribute [rw] trace
+ # @return [Array<String>, nil] Execution trace information for debugging
  class Result
  attr_reader :value, :meta
  attr_accessor :trace
 
- # Initializes a new Result instance.
+ # Initializes a new Result instance with a value and optional context.
+ #
+ # @param value [Object] The value to be wrapped in the result
+ # @param err [String, nil] Optional error message or error object
+ # @param meta [Hash] Optional metadata for additional context
+ # @param trace [Array<String>, nil] Optional execution trace for debugging
  #
- # @param value [Object] the value to be wrapped in the result
- # @param err [String, nil] an optional error message
- # @param meta [Hash] optional metadata
- # @param trace [Array] optional trace
+ # @example Basic initialization
+ # result = Result.new("Success")
+ #
+ # @example With full context
+ # result = Result.new(
+ # "Partial success",
+ # err: "Some records failed",
+ # meta: { processed: 10, failed: 2 },
+ # trace: caller
+ # )
  def initialize(value, err: nil, meta: {}, trace: nil)
  @value = value
  @err = err
  @meta = meta
  @trace = trace
  end
 
- # Returns the result instance itself.
+ # Returns self to provide a consistent interface across result types.
+ # This method ensures that all result objects can be treated uniformly
+ # when chaining operations.
  #
- # @return [HatiCommand::Result] the result instance
+ # @return [HatiCommand::Result] The result instance itself
+ # @api public
  def result
  self
  end
 
- # Returns the error message associated with the result.
+ # Returns the error associated with this result.
+ # This can be used to check for warnings or errors even in successful results.
  #
- # @return [String, nil] the error message
- # @raise [StandardError] if there is an error message
+ # @return [String, nil] The error message or object, if any
+ # @raise [StandardError] If accessing the error triggers an error condition
+ # @api public
+ # @example
+ # result = Result.new("Value", err: "Warning message")
+ # result.error # => "Warning message"
  def error
  @err
  end
 
+ # Returns the symbolic representation of this result type.
+ # This is an abstract method that should be overridden by concrete result types.
+ #
+ # @return [Symbol] Returns :undefined for the base class
+ # @abstract Subclasses must override this method
+ # @api public
+ # @example
+ # Result.new("value").to_sym # => :undefined
  def to_sym
  :undefined
  end

lib/hati_command/success.rb

@@ -1,43 +1,93 @@
 # frozen_string_literal: true
 
+# @module HatiCommand
+# Provides command handling functionalities and result objects.
 module HatiCommand
- # This class represents a successful result.
+ # @class Success
+ # Represents a successful result in the Result pattern.
+ # This class is used to wrap successful operation values and provide a consistent interface
+ # for handling both successful and failed operations.
  #
- # @example
- # success_result = HatiCommand::Success.new("Operation completed successfully")
- # success_result.success # => "Operation completed successfully"
- # success_result.success? # => true
- # success_result.failure # => nil
- # success_result.failure? # => false
+ # The Success class is part of the Result pattern implementation, working alongside
+ # the Failure class to provide a type-safe way to handle operation outcomes.
+ #
+ # @example Basic usage
+ # success = HatiCommand::Success.new("Operation completed")
+ # success.success? # => true
+ # success.failure? # => false
+ #
+ # @example With metadata
+ # success = HatiCommand::Success.new(
+ # { id: 123, name: "Example" },
+ # meta: { duration_ms: 50 }
+ # )
+ # success.success # => { id: 123, name: "Example" }
+ #
+ # @example Pattern matching
+ # case result
+ # when HatiCommand::Success
+ # process_data(result.success)
+ # end
+ #
+ # @see HatiCommand::Failure
+ # @see HatiCommand::Result
  class Success < Result
- # Returns the value associated with the success.
+ # Returns the success value wrapped by this Success instance.
+ # This method provides access to the actual value or result
+ # that was produced by the successful operation.
  #
- # @return [Object] the value of the success
+ # @return [Object] The wrapped success value
+ # @example
+ # success = Success.new("Operation output")
+ # success.success # => "Operation output"
  def success
  value
  end
 
- # Indicates whether the result is a success.
+ # Indicates that this is a success result.
+ # This method is part of the Result pattern interface and always
+ # returns true for Success instances.
  #
- # @return [Boolean] true since this is a success
+ # @return [Boolean] Always returns true
+ # @example
+ # success = Success.new("Result")
+ # success.success? # => true
  def success?
  true
  end
 
- # Returns nil as there is no failure value in a success.
+ # Returns nil since a Success has no failure value.
+ # This method is part of the Result pattern interface and always
+ # returns nil for Success instances.
  #
- # @return [nil]
+ # @return [nil] Always returns nil
+ # @example
+ # success = Success.new("Result")
+ # success.failure # => nil
  def failure
  nil
  end
 
- # Indicates whether the result is a failure.
+ # Indicates that this is not a failure result.
+ # This method is part of the Result pattern interface and always
+ # returns false for Success instances.
  #
- # @return [Boolean] false since this is a success
+ # @return [Boolean] Always returns false
+ # @example
+ # success = Success.new("Result")
+ # success.failure? # => false
  def failure?
  false
  end
 
+ # Returns the symbolic representation of this result type.
+ # Useful for pattern matching and result type checking.
+ #
+ # @return [Symbol] Always returns :success
+ # @api public
+ # @example
+ # success = Success.new("Result")
+ # success.to_sym # => :success
  def to_sym
  :success
  end