cmdx 1.0.1 → 1.1.1

data/lib/cmdx/lazy_struct.rb

@@ -1,81 +1,28 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # LazyStruct provides a flexible, hash-like data structure with dynamic method access
-  # and lazy attribute definition. It serves as the foundation for CMDx's Context system,
-  # allowing for dynamic parameter access and manipulation with both hash-style and
-  # method-style syntax.
+  # Flexible struct-like object with symbol-based attribute access and dynamic assignment.
   #
-  # LazyStruct combines the flexibility of a Hash with the convenience of method access,
-  # automatically creating getter and setter methods for any key-value pairs stored within it.
-  # All keys are normalized to symbols for consistent access patterns.
-  #
-  #
-  # @example Basic usage
-  #   struct = LazyStruct.new(name: "John", age: 30)
-  #   struct.name        #=> "John"
-  #   struct.age         #=> 30
-  #   struct[:name]      #=> "John"
-  #   struct["age"]      #=> 30
-  #
-  # @example Dynamic attribute assignment
-  #   struct = LazyStruct.new
-  #   struct.email = "john@example.com"
-  #   struct[:phone] = "555-1234"
-  #   struct["address"] = "123 Main St"
-  #
-  #   struct.email       #=> "john@example.com"
-  #   struct.phone       #=> "555-1234"
-  #   struct.address     #=> "123 Main St"
-  #
-  # @example Hash-like operations
-  #   struct = LazyStruct.new(name: "John")
-  #   struct.merge!(age: 30, city: "NYC")
-  #   struct.delete!(:city)
-  #   struct.to_h        #=> {:name => "John", :age => 30}
-  #
-  # @example Nested data access
-  #   struct = LazyStruct.new(user: {profile: {name: "John"}})
-  #   struct.dig(:user, :profile, :name)  #=> "John"
-  #
-  # @example Usage in CMDx Context
-  #   class ProcessUserTask < CMDx::Task
-  #     required :user_id, type: :integer
-  #
-  #     def call
-  #       context.user = User.find(user_id)
-  #       context.processed_at = Time.now
-  #       context.result_data = {status: "complete"}
-  #     end
-  #   end
-  #
-  #   result = ProcessUserTask.call(user_id: 123)
-  #   result.context.user         #=> <User id: 123>
-  #   result.context.processed_at #=> 2023-01-01 12:00:00 UTC
-  #
-  # @see Context Context class that inherits from LazyStruct
-  # @see Configuration Configuration class that uses LazyStruct
-  # @since 1.0.0
+  # LazyStruct provides a hash-like object that automatically converts string keys to symbols
+  # and supports both hash-style and method-style attribute access. It's designed for
+  # storing and accessing dynamic attributes with lazy evaluation and flexible assignment patterns.
   class LazyStruct
 
-    ##
-    # Initializes a new LazyStruct with the given data.
-    # The input must respond to `to_h` for hash conversion.
+    # Creates a new LazyStruct instance with the provided attributes.
     #
-    # @param args [Hash, #to_h] initial data for the struct
-    # @raise [ArgumentError] if args doesn't respond to `to_h`
+    # @param args [Hash, #to_h] initial attributes for the struct
     #
-    # @example With hash
-    #   struct = LazyStruct.new(name: "John", age: 30)
+    # @return [LazyStruct] a new LazyStruct instance
     #
-    # @example With hash-like object
-    #   params = ActionController::Parameters.new(name: "John")
-    #   struct = LazyStruct.new(params)
+    # @raise [ArgumentError] if args doesn't respond to to_h
     #
-    # @example Empty initialization
-    #   struct = LazyStruct.new
-    #   struct.name = "John"  # Dynamic assignment
+    # @example Create with hash attributes
+    #   struct = LazyStruct.new(name: "John", age: 30)
+    #   struct.name #=> "John"
+    #
+    # @example Create with hash-like object
+    #   struct = LazyStruct.new(OpenStruct.new(status: "active"))
+    #   struct.status #=> "active"
     def initialize(args = {})
       unless args.respond_to?(:to_h)
         raise ArgumentError,
@@ -85,162 +32,160 @@ module CMDx
       @table = args.to_h.transform_keys { |k| symbolized_key(k) }
     end
 
-    ##
-    # Retrieves a value by key using hash-style access.
-    # Keys are automatically converted to symbols.
+    # Retrieves the value for the specified key.
+    #
+    # @param key [Symbol, String] the key to look up
     #
-    # @param key [Symbol, String] the key to retrieve
-    # @return [Object, nil] the stored value or nil if not found
+    # @return [Object, nil] the value associated with the key, or nil if not found
     #
-    # @example
-    #   struct[:name]    #=> "John"
-    #   struct["name"]   #=> "John"
-    #   struct[:missing] #=> nil
+    # @example Access attribute by symbol
+    #   struct = LazyStruct.new(name: "John")
+    #   struct[:name] #=> "John"
+    #
+    # @example Access attribute by string
+    #   struct[:name] #=> "John"
+    #   struct["name"] #=> "John"
     def [](key)
       table[symbolized_key(key)]
     end
 
-    ##
-    # Retrieves a value by key with error handling and default support.
-    # Similar to Hash#fetch, raises KeyError if key not found and no default given.
+    # Retrieves the value for the specified key or returns/yields a default.
     #
-    # @param key [Symbol, String] the key to retrieve
-    # @param args [Array] default value if key not found
-    # @return [Object] the stored value or default
-    # @raise [KeyError] if key not found and no default provided
+    # @param key [Symbol, String] the key to look up
+    # @param args [Array] additional arguments passed to Hash#fetch
     #
-    # @example With existing key
-    #   struct.fetch!(:name)  #=> "John"
+    # @return [Object] the value associated with the key, or default value
     #
-    # @example With default value
-    #   struct.fetch!(:missing, "default")  #=> "default"
+    # @raise [KeyError] if key is not found and no default is provided
     #
-    # @example With block default
-    #   struct.fetch!(:missing) { "computed default" }  #=> "computed default"
+    # @example Fetch with default value
+    #   struct = LazyStruct.new(name: "John")
+    #   struct.fetch!(:age, 25) #=> 25
     #
-    # @example Key not found
-    #   struct.fetch!(:missing)  #=> raises KeyError
+    # @example Fetch with block default
+    #   struct.fetch!(:missing) { "default" } #=> "default"
     def fetch!(key, ...)
       table.fetch(symbolized_key(key), ...)
     end
 
-    ##
-    # Stores a value by key, converting the key to a symbol.
+    # Stores a value for the specified key.
     #
-    # @param key [Symbol, String] the key to store under
+    # @param key [Symbol, String] the key to store the value under
     # @param value [Object] the value to store
+    #
     # @return [Object] the stored value
     #
-    # @example
-    #   struct.store!(:name, "John")
-    #   struct.store!("age", 30)
-    #   struct.name  #=> "John"
-    #   struct.age   #=> 30
+    # @example Store a value
+    #   struct = LazyStruct.new
+    #   struct.store!(:name, "John") #=> "John"
+    #   struct.name #=> "John"
     def store!(key, value)
       table[symbolized_key(key)] = value
     end
     alias []= store!
 
-    ##
-    # Merges another hash-like object into this struct.
-    # All keys from the source are converted to symbols.
+    # Merges the provided arguments into the struct's attributes.
+    #
+    # @param args [Hash, #to_h] attributes to merge into the struct
     #
-    # @param args [Hash, #to_h] data to merge into this struct
     # @return [LazyStruct] self for method chaining
     #
-    # @example
+    # @example Merge attributes
     #   struct = LazyStruct.new(name: "John")
     #   struct.merge!(age: 30, city: "NYC")
-    #   struct.to_h  #=> {:name => "John", :age => 30, :city => "NYC"}
+    #   struct.age #=> 30
     def merge!(args = {})
       args.to_h.each { |key, value| store!(symbolized_key(key), value) }
       self
     end
 
-    ##
-    # Deletes a key-value pair from the struct.
+    # Deletes the specified key from the struct.
     #
     # @param key [Symbol, String] the key to delete
-    # @param block [Proc] optional block to execute if key not found
-    # @return [Object, nil] the deleted value or result of block
+    # @param block [Proc] optional block to yield if key is not found
+    #
+    # @return [Object, nil] the deleted value, or result of block if key not found
+    #
+    # @example Delete an attribute
+    #   struct = LazyStruct.new(name: "John", age: 30)
+    #   struct.delete!(:age) #=> 30
+    #   struct.age #=> nil
     #
-    # @example
-    #   struct.delete!(:name)     #=> "John"
-    #   struct.delete!(:missing)  #=> nil
-    #   struct.delete!(:missing) { "not found" }  #=> "not found"
+    # @example Delete with default block
+    #   struct.delete!(:missing) { "not found" } #=> "not found"
     def delete!(key, &)
       table.delete(symbolized_key(key), &)
     end
     alias delete_field! delete!
 
-    ##
-    # Compares this struct with another for equality.
-    # Two LazyStructs are equal if they have the same class and hash representation.
+    # Checks equality with another object.
     #
-    # @param other [Object] object to compare with
-    # @return [Boolean] true if structs are equal
+    # @param other [Object] the object to compare against
     #
-    # @example
+    # @return [Boolean] true if other is a LazyStruct with identical attributes
+    #
+    # @example Compare structs
     #   struct1 = LazyStruct.new(name: "John")
     #   struct2 = LazyStruct.new(name: "John")
-    #   struct1 == struct2  #=> true
-    #   struct1.eql?(struct2)  #=> true
+    #   struct1.eql?(struct2) #=> true
     def eql?(other)
       other.is_a?(self.class) && (to_h == other.to_h)
     end
     alias == eql?
 
-    ##
-    # Retrieves nested values using a sequence of keys.
-    # Similar to Hash#dig, safely navigates nested structures.
-    #
-    # @param key [Symbol, String] the first key to access
-    # @param keys [Array<Symbol, String>] additional keys for nested access
-    # @return [Object, nil] the nested value or nil if path doesn't exist
-    # @raise [TypeError] if key cannot be converted to symbol
-    #
-    # @example
-    #   struct = LazyStruct.new(user: {profile: {name: "John"}})
-    #   struct.dig(:user, :profile, :name)  #=> "John"
-    #   struct.dig(:user, :missing, :name)  #=> nil
+    # Extracts nested values using key path traversal.
+    #
+    # @param key [Symbol, String] the initial key to look up
+    # @param keys [Array<Symbol, String>] additional keys for nested traversal
+    #
+    # @return [Object, nil] the nested value, or nil if any key in the path is missing
+    #
+    # @example Dig into nested structure
+    #   struct = LazyStruct.new(user: { profile: { name: "John" } })
+    #   struct.dig(:user, :profile, :name) #=> "John"
+    #   struct.dig(:user, :missing, :name) #=> nil
     def dig(key, *keys)
       table.dig(symbolized_key(key), *keys)
     end
 
-    ##
     # Iterates over each key-value pair in the struct.
     #
-    # @yieldparam key [Symbol] the key
-    # @yieldparam value [Object] the value
-    # @return [LazyStruct] self if block given, Enumerator otherwise
+    # @param block [Proc] the block to execute for each key-value pair
+    #
+    # @return [Enumerator, LazyStruct] an enumerator if no block given, self otherwise
     #
-    # @example
+    # @example Iterate over pairs
+    #   struct = LazyStruct.new(name: "John", age: 30)
     #   struct.each_pair { |key, value| puts "#{key}: #{value}" }
+    #   # Output: name: John
+    #   #         age: 30
     def each_pair(&)
       table.each_pair(&)
     end
 
-    ##
     # Converts the struct to a hash representation.
     #
-    # @param block [Proc] optional block for hash transformation
-    # @return [Hash] hash representation with symbol keys
+    # @param block [Proc] optional block for transforming key-value pairs
+    #
+    # @return [Hash] a hash containing all the struct's attributes
     #
-    # @example
+    # @example Convert to hash
     #   struct = LazyStruct.new(name: "John", age: 30)
-    #   struct.to_h  #=> {:name => "John", :age => 30}
+    #   struct.to_h #=> { name: "John", age: 30 }
+    #
+    # @example Convert with transformation
+    #   struct.to_h { |k, v| [k.to_s, v.to_s] } #=> { "name" => "John", "age" => "30" }
     def to_h(&)
       table.to_h(&)
     end
 
-    ##
-    # Returns a string representation of the struct showing all key-value pairs.
+    # Returns a string representation of the struct for debugging.
     #
-    # @return [String] formatted string representation
+    # @return [String] a formatted string showing the class name and attributes
     #
-    # @example
+    # @example Inspect struct
     #   struct = LazyStruct.new(name: "John", age: 30)
-    #   struct.inspect  #=> '#<CMDx::LazyStruct:name="John" :age=30>'
+    #   struct.inspect #=> "#<CMDx::LazyStruct :name=\"John\" :age=30>"
     def inspect
       "#<#{self.class.name}#{table.map { |key, value| ":#{key}=#{value.inspect}" }.join(' ')}>"
     end
@@ -248,70 +193,49 @@ module CMDx
 
     private
 
+    # Returns the internal hash table storing the struct's attributes.
+    #
+    # @return [Hash] the internal attribute storage
     def table
       @table ||= {}
     end
 
-    ##
     # Handles dynamic method calls for attribute access and assignment.
-    # Getter methods return the stored value, setter methods (ending with =) store values.
     #
     # @param method_name [Symbol] the method name being called
     # @param args [Array] arguments passed to the method
-    # @return [Object] the stored value for getters, the assigned value for setters
-    #
-    # @example Getter methods
-    #   struct.name        # Calls method_missing(:name)
-    #   struct.undefined   # Calls method_missing(:undefined) => nil
+    # @param _kwargs [Hash] keyword arguments (unused)
+    # @param block [Proc] block passed to the method (unused)
     #
-    # @example Setter methods
-    #   struct.name = "John"  # Calls method_missing(:name=, "John")
+    # @return [Object, nil] the attribute value for getters, or the assigned value for setters
     #
-    # @api private
+    # @example Dynamic attribute access
+    #   struct = LazyStruct.new(name: "John")
+    #   struct.name #=> "John"
+    #   struct.age = 30 #=> 30
     def method_missing(method_name, *args, **_kwargs, &)
       table.fetch(symbolized_key(method_name)) do
         store!(method_name[0..-2], args.first) if method_name.end_with?("=")
       end
     end
 
-    ##
-    # Determines if the struct responds to a given method name.
-    # Returns true for any key in the internal table or standard methods.
+    # Checks if the struct responds to a method name.
     #
     # @param method_name [Symbol] the method name to check
     # @param include_private [Boolean] whether to include private methods
-    # @return [Boolean] true if the struct responds to the method
-    #
-    # @example
-    #   struct = LazyStruct.new(name: "John")
-    #   struct.respond_to?(:name)     #=> true
-    #   struct.respond_to?(:missing)  #=> false
-    #   struct.respond_to?(:to_h)     #=> true
     #
-    # @api private
+    # @return [Boolean] true if the struct has the attribute or responds to the method
     def respond_to_missing?(method_name, include_private = false)
       table.key?(symbolized_key(method_name)) || super
     end
 
-    ##
     # Converts a key to a symbol for consistent internal storage.
-    # This method normalizes all keys to symbols regardless of their input type,
-    # ensuring consistent access patterns throughout the LazyStruct.
-    #
-    # @param key [Object] the key to convert to a symbol
-    # @return [Symbol] the key converted to a symbol
-    # @raise [TypeError] if the key cannot be converted to a symbol (doesn't respond to `to_sym`)
     #
-    # @example Valid key conversion
-    #   symbolized_key("name")    #=> :name
-    #   symbolized_key(:name)     #=> :name
-    #   symbolized_key("123")     #=> :"123"
+    # @param key [Symbol, String, Object] the key to convert
     #
-    # @example Invalid key conversion
-    #   symbolized_key(Object.new)  #=> raises TypeError
-    #   symbolized_key(123)         #=> raises TypeError
+    # @return [Symbol] the symbolized key
     #
-    # @api private
+    # @raise [TypeError] if the key cannot be converted to a symbol
     def symbolized_key(key)
       key.to_sym
     rescue NoMethodError

data/lib/cmdx/log_formatters/json.rb

@@ -2,54 +2,28 @@
 
 module CMDx
   module LogFormatters
-    # JSON log formatter for CMDx logging system.
+    # JSON log formatter that outputs structured log entries as JSON.
     #
-    # Formats log entries as single-line JSON objects containing task execution metadata
-    # including severity, timestamp, process ID, and serialized task information.
-    # Ideal for structured logging systems that need to parse log data programmatically.
-    #
-    # @example Basic usage with global logger configuration
-    #   CMDx.configure do |config|
-    #     config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Json.new)
-    #   end
-    #
-    # @example Task-specific formatter configuration
-    #   class ProcessOrderTask < CMDx::Task
-    #     task_settings!(log_format: CMDx::LogFormatters::Json.new)
-    #
-    #     def call
-    #       logger.info "Processing order #{order_id}"
-    #     end
-    #   end
-    #
-    # @example Sample JSON output
-    #   {"severity":"INFO","pid":1234,"timestamp":"2022-07-17T18:43:15.000000","index":0,"chain_id":"018c2b95-b764-7615","type":"Task","class":"ProcessOrderTask","id":"018c2b95-b764-7615","tags":[],"state":"complete","status":"success","outcome":"success","metadata":{},"runtime":15,"origin":"CMDx"}
-    #
-    # @see CMDx::LogFormatters::PrettyJson For human-readable JSON formatting
-    # @see CMDx::LoggerSerializer For details on serialized data structure
+    # This formatter converts log entries into JSON format, including metadata
+    # such as severity, process ID, and timestamp. Each log entry is output as
+    # a single line of JSON followed by a newline character.
     class Json
 
-      # Formats a log entry as a single-line JSON string.
+      # Formats a log entry as a JSON string.
       #
-      # Combines task execution metadata with severity, process ID, and timestamp
-      # information to create a comprehensive JSON log entry suitable for
-      # structured logging systems and log aggregation tools.
+      # @param severity [String] the log severity level (e.g., "INFO", "ERROR")
+      # @param time [Time] the timestamp when the log entry was created
+      # @param task [Object] the task object associated with the log entry
+      # @param message [String] the log message content
       #
-      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
-      # @param time [Time] Timestamp when the log entry was created
-      # @param task [CMDx::Task] Task instance being logged
-      # @param message [Object] Log message or data to be included
+      # @return [String] the formatted JSON log entry with trailing newline
       #
-      # @return [String] Single-line JSON string with newline terminator
+      # @raise [JSON::GeneratorError] if the log data cannot be serialized to JSON
       #
-      # @example Success log entry
+      # @example Formatting a log entry
       #   formatter = CMDx::LogFormatters::Json.new
-      #   output = formatter.call("INFO", Time.now, task, "Order processed")
-      #   # => {"severity":"INFO","pid":1234,...}\n
-      #
-      # @example Error log entry with metadata
-      #   output = formatter.call("ERROR", Time.now, task, error_details)
-      #   # => {"severity":"ERROR","pid":1234,"caused_failure":{...},...}\n
+      #   result = formatter.call("INFO", Time.now, task_object, "Task completed")
+      #   #=> "{\"severity\":\"INFO\",\"pid\":12345,\"timestamp\":\"2024-01-01T12:00:00Z\",\"message\":\"Task completed\"}\n"
       def call(severity, time, task, message)
         m = LoggerSerializer.call(severity, time, task, message).merge!(
           severity:,

data/lib/cmdx/log_formatters/key_value.rb

@@ -2,54 +2,28 @@
 
 module CMDx
   module LogFormatters
-    # Key-value log formatter for CMDx logging system.
+    # Key-value log formatter that outputs structured log entries as key=value pairs.
     #
-    # Formats log entries as space-separated key=value pairs on a single line.
-    # Provides a compact, structured format that is easily parseable by log
-    # processing tools while remaining human-readable for basic inspection.
-    #
-    # @example Basic usage with global logger configuration
-    #   CMDx.configure do |config|
-    #     config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::KeyValue.new)
-    #   end
-    #
-    # @example Task-specific formatter configuration
-    #   class ProcessOrderTask < CMDx::Task
-    #     task_settings!(log_format: CMDx::LogFormatters::KeyValue.new)
-    #
-    #     def call
-    #       logger.info "Processing order #{order_id}"
-    #     end
-    #   end
-    #
-    # @example Sample key-value output
-    #   severity=INFO pid=1234 timestamp=2022-07-17T18:43:15.000000 index=0 chain_id=018c2b95-b764-7615 type=Task class=ProcessOrderTask id=018c2b95-b764-7615 tags=[] state=complete status=success outcome=success metadata={} runtime=15 origin=CMDx
-    #
-    # @see CMDx::LogFormatters::PrettyKeyValue For ANSI-colorized key-value formatting
-    # @see CMDx::LoggerSerializer For details on serialized data structure
+    # This formatter converts log entries into key-value format, including metadata
+    # such as severity, process ID, and timestamp. Each log entry is output as
+    # space-separated key=value pairs followed by a newline character.
     class KeyValue
 
-      # Formats a log entry as space-separated key=value pairs.
+      # Formats a log entry as a key=value string.
       #
-      # Combines task execution metadata with severity, process ID, and timestamp
-      # information to create a compact key-value log entry suitable for
-      # structured logging systems that prefer flat field formats.
+      # @param severity [String] the log severity level (e.g., "INFO", "ERROR")
+      # @param time [Time] the timestamp when the log entry was created
+      # @param task [Object] the task object associated with the log entry
+      # @param message [String] the log message content
       #
-      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
-      # @param time [Time] Timestamp when the log entry was created
-      # @param task [CMDx::Task] Task instance being logged
-      # @param message [Object] Log message or data to be included
+      # @return [String] the formatted key=value log entry with trailing newline
       #
-      # @return [String] Single-line key=value formatted string with newline terminator
+      # @raise [StandardError] if the log data cannot be serialized to key=value format
       #
-      # @example Success log entry
+      # @example Formatting a log entry
       #   formatter = CMDx::LogFormatters::KeyValue.new
-      #   output = formatter.call("INFO", Time.now, task, "Order processed")
-      #   # => "severity=INFO pid=1234 timestamp=... status=success\n"
-      #
-      # @example Error log entry with failure metadata
-      #   output = formatter.call("ERROR", Time.now, task, error_details)
-      #   # => "severity=ERROR pid=1234 ... caused_failure={...} threw_failure={...}\n"
+      #   result = formatter.call("INFO", Time.now, task_object, "Task completed")
+      #   #=> "severity=INFO pid=12345 timestamp=2024-01-01T12:00:00Z message=Task completed\n"
       def call(severity, time, task, message)
         m = LoggerSerializer.call(severity, time, task, message).merge!(
           severity:,

data/lib/cmdx/log_formatters/line.rb

@@ -2,62 +2,28 @@
 
 module CMDx
   module LogFormatters
-    # Line log formatter for CMDx logging system.
+    # Line log formatter that outputs log entries in a traditional line format.
     #
-    # Formats log entries in a traditional single-line format similar to Ruby's
-    # standard Logger output. Combines severity indicators, timestamps, process
-    # information, and task details in a compact, readable format suitable for
-    # standard logging environments.
-    #
-    # @example Basic usage with global logger configuration
-    #   CMDx.configure do |config|
-    #     config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
-    #   end
-    #
-    # @example Task-specific formatter configuration
-    #   class ProcessOrderTask < CMDx::Task
-    #     task_settings!(log_format: CMDx::LogFormatters::Line.new)
-    #
-    #     def call
-    #       logger.info "Processing order #{order_id}"
-    #     end
-    #   end
-    #
-    # @example Sample line output
-    #   I, [2022-07-17T18:43:15.000000 #1234] INFO -- ProcessOrderTask: state=complete status=success outcome=success runtime=15
-    #
-    # @example Error line output with failure details
-    #   E, [2022-07-17T18:43:15.000000 #1234] ERROR -- ProcessOrderTask: state=interrupted status=failed outcome=failed caused_failure={...}
-    #
-    # @see CMDx::LogFormatters::PrettyLine For ANSI-colorized line formatting
-    # @see CMDx::LoggerSerializer For details on serialized data structure
-    # @see CMDx::Utils::LogTimestamp For timestamp formatting
+    # This formatter converts log entries into a human-readable line format,
+    # including metadata such as severity, process ID, and timestamp. Each log
+    # entry is output as a single line with structured information.
     class Line
 
-      # Formats a log entry as a traditional single-line log entry.
+      # Formats a log entry as a line string.
       #
-      # Creates a log entry in the format: "SEVERITY_INITIAL, [TIMESTAMP #PID] SEVERITY -- CLASS: MESSAGE"
-      # where MESSAGE contains key=value pairs of task execution metadata.
+      # @param severity [String] the log severity level (e.g., "INFO", "ERROR")
+      # @param time [Time] the timestamp when the log entry was created
+      # @param task [Object] the task object associated with the log entry
+      # @param message [String] the log message content
       #
-      # @param severity [String] Log severity level (DEBUG, INFO, WARN, ERROR, FATAL)
-      # @param time [Time] Timestamp when the log entry was created
-      # @param task [CMDx::Task] Task instance being logged
-      # @param message [Object] Log message or data to be included
+      # @return [String] the formatted line log entry with trailing newline
       #
-      # @return [String] Single-line formatted log entry with newline terminator
+      # @raise [NoMethodError] if the task object doesn't respond to expected methods
       #
-      # @example Success log entry
+      # @example Formatting a log entry
       #   formatter = CMDx::LogFormatters::Line.new
-      #   output = formatter.call("INFO", Time.now, task, "Order processed")
-      #   # => "I, [2022-07-17T18:43:15.000000 #1234] INFO -- ProcessOrderTask: state=complete status=success\n"
-      #
-      # @example Debug log entry with detailed metadata
-      #   output = formatter.call("DEBUG", Time.now, task, debug_info)
-      #   # => "D, [2022-07-17T18:43:15.000000 #1234] DEBUG -- ProcessOrderTask: index=0 chain_id=... metadata={...}\n"
-      #
-      # @example Error log entry with failure chain
-      #   output = formatter.call("ERROR", Time.now, task, error_details)
-      #   # => "E, [2022-07-17T18:43:15.000000 #1234] ERROR -- ProcessOrderTask: status=failed caused_failure={...} threw_failure={...}\n"
+      #   result = formatter.call("INFO", Time.now, task_object, "Task completed")
+      #   #=> "I, [2024-01-01T12:00:00.000Z #12345] INFO -- TaskClass: Task completed\n"
       def call(severity, time, task, message)
         t = Utils::LogTimestamp.call(time.utc)
         m = LoggerSerializer.call(severity, time, task, message)