100% documentation coverage.

Author: ioquatix

lib/async/service.rb

@@ -6,3 +6,10 @@
 require_relative "service/configuration"
 require_relative "service/controller"
 require_relative "service/version"
+
+# @namespace
+module Async
+	# @namespace
+	module Service
+	end
+end

lib/async/service/configuration.rb

@@ -13,6 +13,10 @@ module Service
 		#
 		# Environments are key-value maps with lazy value resolution. An environment can inherit from a parent environment, which can provide defaults
 		class Configuration
+			# Build a configuration using a block.
+			# @parameter root [String] The root directory for loading files.
+			# @yields {|loader| ...} A loader instance for configuration.
+			# @returns [Configuration] A new configuration instance.
 			def self.build(root: Dir.pwd, &block)
 				configuration = self.new
 
@@ -22,6 +26,9 @@ def self.build(root: Dir.pwd, &block)
 				return configuration
 			end
 
+			# Load configuration from file paths.
+			# @parameter paths [Array(String)] File paths to load, defaults to `ARGV`.
+			# @returns [Configuration] A new configuration instance.
 			def self.load(paths = ARGV)
 				configuration = self.new
 
@@ -32,6 +39,9 @@ def self.load(paths = ARGV)
 				return configuration
 			end
 
+			# Create configuration from environments.
+			# @parameter environments [Array] Environment instances.
+			# @returns [Configuration] A new configuration instance.
 			def self.for(*environments)
 				self.new(environments)
 			end
@@ -43,6 +53,8 @@ def initialize(environments = [])
 
 			attr :environments
 
+			# Check if the configuration is empty.
+			# @returns [Boolean] True if no environments are configured.
 			def empty?
 				@environments.empty?
 			end

lib/async/service/container_service.rb

@@ -8,13 +8,23 @@
 
 module Async
 	module Service
+		# A service that runs in a container with built-in health checking and process title formatting.
+		#
+		# This is the recommended base class for most services.
 		class ContainerService < Async::Service::Generic
 			include Async::Service::Formatting
 
 			private def format_title(evaluator, server)
 				"#{evaluator.name} #{server.to_s}"
 			end
 
+			# Run the service logic.
+			#
+			# Override this method to implement your service. Return an object that represents the running service (e.g., a server, task, or worker pool) for health checking.
+			#
+			# @parameter instance [Object] The container instance.
+			# @parameter evaluator [Environment::Evaluator] The environment evaluator.
+			# @returns [Object] The service object (server, task, etc.)
 			def run(instance, evaluator)
 				Async do
 					sleep
@@ -37,12 +47,15 @@ def preload!
 				Console.warn(self, "Service preload failed!", error)
 			end
 
+			# Start the service, including preloading resources.
 			def start
 				preload!
 
 				super
 			end
 
+			# Set up the container with health checking and process title formatting.
+			# @parameter container [Async::Container] The container to configure.
 			def setup(container)
 				super
 

lib/async/service/controller.rb

@@ -7,7 +7,13 @@
 
 module Async
 	module Service
+		# Controls multiple services and their lifecycle.
+		#
+		# The controller manages starting, stopping, and monitoring multiple services
+		# within containers. It extends Async::Container::Controller to provide
+		# service-specific functionality.
 		class Controller < Async::Container::Controller
+			# Warm up the Ruby process by preloading gems and running GC.
 			def self.warmup
 				begin
 					require "bundler"
@@ -24,6 +30,9 @@ def self.warmup
 				end
 			end
 
+			# Run a configuration of services.
+			# @parameter configuration [Configuration] The service configuration to run.
+			# @parameter options [Hash] Additional options for the controller.
 			def self.run(configuration, **options)
 				controller = Async::Service::Controller.new(configuration.services.to_a, **options)
 
@@ -32,10 +41,17 @@ def self.run(configuration, **options)
 				controller.run
 			end
 
+			# Create a controller for the given services.
+			# @parameter services [Array(Generic)] The services to control.
+			# @parameter options [Hash] Additional options for the controller.
+			# @returns [Controller] A new controller instance.
 			def self.for(*services, **options)
 				self.new(services, **options)
 			end
 
+			# Initialize a new controller with services.
+			# @parameter services [Array(Generic)] The services to manage.
+			# @parameter options [Hash] Options passed to the parent controller.
 			def initialize(services, **options)
 				super(**options)
 

lib/async/service/environment.rb

@@ -5,8 +5,17 @@
 
 module Async
 	module Service
+		# Represents a service configuration with lazy evaluation and module composition.
+		#
+		# Environments store configuration as methods that can be overridden and composed using Ruby modules. They support lazy evaluation through evaluators.
 		class Environment
+			# A builder for constructing environments using a DSL.
 			class Builder < BasicObject
+				# Create a new environment with facets and values.
+				# @parameter facets [Array(Module)] Modules to include in the environment.
+				# @parameter values [Hash] Key-value pairs to define as methods.
+				# @parameter block [Proc] A block for additional configuration.
+				# @returns [Module] The constructed environment module.
 				def self.for(*facets, **values, &block)
 					top = ::Module.new
 
@@ -46,10 +55,14 @@ def self.for(*facets, **values, &block)
 					return top
 				end
 
+				# Initialize a new builder.
+				# @parameter facet [Module] The module to build into, defaults to a new `Module`.
 				def initialize(facet = ::Module.new)
 					@facet = facet
 				end
 
+				# Include a module or other includable object into the environment.
+				# @parameter target [Module] The module to include.
 				def include(target)
 					if target.class == ::Module
 						@facet.include(target)
@@ -60,6 +73,10 @@ def include(target)
 					end
 				end
 
+				# Define methods dynamically on the environment.
+				# @parameter name [Symbol] The method name to define.
+				# @parameter argument [Object] The value to return from the method.
+				# @parameter block [Proc] A block to use as the method implementation.
 				def method_missing(name, argument = nil, &block)
 					if block
 						@facet.define_method(name, &block)
@@ -68,15 +85,25 @@ def method_missing(name, argument = nil, &block)
 					end
 				end
 
+				# Always respond to missing methods for dynamic method definition.
+				# @parameter name [Symbol] The method name.
+				# @parameter include_private [Boolean] Whether to include private methods.
+				# @returns [Boolean] Always true to enable dynamic method definition.
 				def respond_to_missing?(name, include_private = false)
 					true
 				end
 			end
 
+			# Build a new environment using the builder DSL.
+			# @parameter arguments [Array] Arguments passed to Builder.for
+			# @returns [Environment] A new environment instance.
 			def self.build(...)
 				Environment.new(Builder.for(...))
 			end
 
+			# Initialize a new environment.
+			# @parameter facet [Module] The facet module containing the configuration methods.
+			# @parameter parent [Environment | Nil] The parent environment for inheritance.
 			def initialize(facet = ::Module.new, parent = nil)
 				unless facet.class == ::Module
 					raise ArgumentError, "Facet must be a module!"
@@ -92,21 +119,32 @@ def initialize(facet = ::Module.new, parent = nil)
 			# @attribute [Environment | Nil] The parent environment, if any.
 			attr :parent
 
+			# Include this environment's facet into a target module.
+			# @parameter target [Module] The target module to include into.
 			def included(target)
 				@parent&.included(target)
 				target.include(@facet)
 			end
 
+			# Create a new environment with additional configuration.
+			# @parameter arguments [Array] Arguments passed to Environment.build.
+			# @returns [Environment] A new environment with this as parent.
 			def with(...)
 				return self.class.new(Builder.for(...), self)
 			end
 
+			# Check if this environment implements a given interface.
+			# @parameter interface [Module] The interface to check.
+			# @returns [Boolean] True if this environment implements the interface.
 			def implements?(interface)
 				@facet <= interface
 			end
 
 			# An evaluator is lazy read-only view of an environment. It memoizes all method calls.
 			class Evaluator
+				# Create an evaluator wrapper for an environment.
+				# @parameter environment [Environment] The environment to wrap.
+				# @returns [Evaluator] A new evaluator instance.
 				def self.wrap(environment)
 					evaluator = ::Class.new(self)
 
@@ -137,14 +175,19 @@ def self.wrap(environment)
 					return evaluator.new
 				end
 
+				# Initialize a new evaluator.
 				def initialize
 					@cache = {}
 				end
 
+				# Inspect representation of the evaluator.
+				# @returns [String] A string representation of the evaluator with its keys.
 				def inspect
 					"#<#{Evaluator} #{self.keys}>"
 				end
 
+				# Convert the evaluator to a hash.
+				# @returns [Hash] A hash with all evaluated keys and values.
 				def to_h
 					# Ensure all keys are evaluated:
 					self.keys.each do |name|
@@ -154,25 +197,38 @@ def to_h
 					return @cache
 				end
 
+				# Convert the evaluator to JSON.
+				# @parameter arguments [Array] Arguments passed to to_json.
+				# @returns [String] A JSON representation of the evaluator.
 				def to_json(...)
 					self.to_h.to_json(...)
 				end
 
+				# Get value for a given key.
+				# @parameter key [Symbol] The key to look up.
+				# @returns [Object, nil] The value for the key, or nil if not found.
 				def [](key)
 					if self.key?(key)
 						self.__send__(key)
 					end
 				end
 
+				# Check if a key is available.
+				# @parameter key [Symbol] The key to check.
+				# @returns [Boolean] True if the key exists.
 				def key?(key)
 					self.keys.include?(key)
 				end
 			end
 
+			# Create an evaluator for this environment.
+			# @returns [Evaluator] A lazy evaluator for this environment.
 			def evaluator
 				return Evaluator.wrap(self)
 			end
 
+			# Convert the environment to a hash.
+			# @returns [Hash] A hash representation of the environment.
 			def to_h
 				evaluator.to_h
 			end

lib/async/service/generic.rb

@@ -33,6 +33,8 @@ def initialize(environment, evaluator = environment.evaluator)
 			# @attribute [Environment] The environment which is used to configure the service.
 			attr :environment
 
+			# Convert the service evaluator to a hash.
+			# @returns [Hash] A hash representation of the evaluator.
 			def to_h
 				@evaluator.to_h
 			end

lib/async/service/loader.rb

@@ -38,6 +38,8 @@ def self.load_file(configuration, path)
 				loader.instance_eval(File.read(path), path)
 			end
 
+			# Load a file relative to the loader's root directory.
+			# @parameter path [String] The path to the file to load.
 			def load_file(path)
 				Loader.load_file(@configuration, File.expand_path(path, @root))
 			end