100% documentation coverage.

Author: ioquatix

lib/teapot.rb

@@ -4,8 +4,4 @@
 # Copyright, 2012-2026, by Samuel Williams.
 
 require "teapot/version"
-
 require "teapot/context"
-
-module Teapot
-end

lib/teapot/command.rb

@@ -23,7 +23,9 @@
 require "console"
 
 module Teapot
+	# @namespace
 	module Command
+		# Represents the top-level command for the teapot CLI.
 		class Top < Samovar::Command
 			self.description = "A decentralised package manager and build tool."
 
@@ -46,18 +48,26 @@ class Top < Samovar::Command
 				"clean" => Clean,
 			}, default: "build"
 
+			# The project root directory, either from --root option or current working directory.
+			# @returns [Build::Files::Path] The root directory path.
 			def root
 				::Build::Files::Path.expand(@options[:root] || Dir.getwd)
 			end
 
+			# Whether verbose logging is enabled via --verbose flag.
+			# @returns [Boolean] True if verbose mode is enabled.
 			def verbose?
 				@options[:logging] == :verbose
 			end
 
+			# Whether quiet logging is enabled via --quiet flag.
+			# @returns [Boolean] True if quiet mode is enabled.
 			def quiet?
 				@options[:logging] == :quiet
 			end
 
+			# Get the logger for the command.
+			# @returns [Console::Logger] The configured logger instance.
 			def logger
 				@logger ||= Console::Logger.new(Console.logger, verbose: self.verbose?).tap do |logger|
 					if verbose?
@@ -70,14 +80,20 @@ def logger
 				end
 			end
 
+			# The build configuration name from -c option or TEAPOT_CONFIGURATION environment variable.
+			# @returns [String | Nil] The configuration name if specified.
 			def configuration
 				@options[:configuration]
 			end
 
+			# Create a context for the project.
+			# @parameter root [Build::Files::Path] The root directory path.
+			# @returns [Context] A new context instance.
 			def context(root = self.root)
 				Context.new(root, configuration: configuration)
 			end
 
+			# Execute the command.
 			def call
 				if @options[:version]
 					puts "teapot v#{Teapot::VERSION}"

lib/teapot/command/build.rb

@@ -9,9 +9,11 @@
 
 module Teapot
 	module Command
+		# Raised when the build fails.
 		class BuildFailedError < StandardError
 		end
 
+		# A command to build targets in the project.
 		class Build < Selection
 			self.description = "Build the specified target."
 
@@ -23,6 +25,8 @@ class Build < Selection
 			many :targets, "Build these targets, or use them to help the dependency resolution process."
 			split :argv, "Arguments passed to child process(es) of build if any."
 
+			# Build the selected targets or default build targets, resolving dependencies and executing the build controller.
+			# @returns [Build::Dependency::Chain] The dependency chain.
 			def call
 				context = parent.context
 
@@ -65,6 +69,8 @@ def call
 				return chain
 			end
 
+			# Display task dependencies for debugging, showing which tasks generate which outputs.
+			# @parameter walker [Build::Walker] The build walker.
 			def show_dependencies(walker)
 				outputs = {}
 

lib/teapot/command/clean.rb

@@ -7,9 +7,11 @@
 
 module Teapot
 	module Command
+		# A command to clean build artifacts.
 		class Clean < Samovar::Command
 			self.description = "Delete everything in the teapot directory."
 
+			# Delete build output directories for the specified targets or all targets.
 			def call
 				context = parent.context
 				logger = parent.logger

lib/teapot/command/clone.rb

@@ -13,11 +13,13 @@
 
 module Teapot
 	module Command
+		# A command to clone a remote repository and fetch all dependencies.
 		class Clone < Samovar::Command
 			self.description = "Clone a remote repository and fetch all dependencies."
 
 			one :source, "The source repository to clone.", required: true
 
+			# Clone packages from their remote repositories using git, parallelizing the operations.
 			def call
 				logger = parent.logger
 
@@ -37,6 +39,11 @@ def call
 				Fetch[parent: nested].call
 			end
 
+			# Provide credentials for repository authentication.
+			# @parameter url [String] The repository URL.
+			# @parameter username [String] The username.
+			# @parameter types [Array] The credential types allowed.
+			# @returns [Rugged::Credentials] The credentials object.
 			def credentials(url, username, types)
 				# We should prompt for username/password if required...
 				return Rugged::Credentials::SshKeyFromAgent.new(username: username)

lib/teapot/command/create.rb

@@ -11,13 +11,15 @@
 
 module Teapot
 	module Command
+		# A command to create a new teapot project.
 		class Create < Samovar::Command
 			self.description = "Create a new teapot package using the specified repository."
 
 			one :name, "The name of the new project in title-case, e.g. 'My Project'.", required: true
 			one :source, "The source repository to use for fetching packages, e.g. https://github.com/kurocha.", required: true
 			many :packages, "Any packages you'd like to include in the project.", default: ["generate-project"]
 
+			# Create a new project directory structure with default teapot.rb configuration.
 			def call
 				logger = parent.logger
 
@@ -64,6 +66,11 @@ def call
 				)
 			end
 
+			# Generate the initial project files.
+			# @parameter root [Build::Files::Path] The project root path.
+			# @parameter name [String] The project name.
+			# @parameter source [String] The source repository URL.
+			# @parameter packages [Array(String)] The packages to include.
 			def generate_project(root, name, source, packages)
 				name = ::Build::Name.new(name)
 

lib/teapot/command/fetch.rb

@@ -8,7 +8,10 @@
 
 module Teapot
 	module Command
+		# Raised when a fetch operation fails.
 		class FetchError < StandardError
+			# @parameter package [Package] The package that caused the error.
+			# @parameter message [String] The error message.
 			def initialize(package, message)
 				super(message)
 				@package = package
@@ -17,6 +20,7 @@ def initialize(package, message)
 			attr :package
 		end
 
+		# A command to fetch remote packages and dependencies.
 		class Fetch < Samovar::Command
 			self.description = "Fetch remote packages according to the specified configuration."
 
@@ -32,10 +36,13 @@ class Fetch < Samovar::Command
 
 			many :packages, "Only update the specified packages, or all packages if none specified."
 
+			# Get the context for this command.
+			# @returns [Context] The current context.
 			def context
 				parent.context
 			end
 
+			# Update packages by pulling latest changes from their git remotes, subject to lock file constraints.
 			def call
 				selection = context.select
 

lib/teapot/command/list.rb

@@ -10,9 +10,13 @@
 
 module Teapot
 	module Command
+		# A command to list project definitions and dependencies.
 		class List < Selection
 			self.description = "List provisions and dependencies of the specified package."
 
+			# Create a terminal with custom styles for colorizing different definition types in output.
+			# @parameter output [IO] The output stream.
+			# @returns [Console::Terminal] The configured terminal.
 			def terminal(output = $stdout)
 				Console::Terminal.for(output).tap do |terminal|
 					terminal[:definition] = terminal.style(nil, nil, :bright)
@@ -24,6 +28,8 @@ def terminal(output = $stdout)
 				end
 			end
 
+			# Process and display the selection.
+			# @parameter selection [Select] The selection to process.
 			def process(selection)
 				context = selection.context
 				terminal = self.terminal

lib/teapot/command/selection.rb

@@ -7,17 +7,23 @@
 
 module Teapot
 	module Command
+		# Base class for commands that work with selections.
 		class Selection < Samovar::Command
 			options
 
 			many :targets, "Only consider the specified targets, if any."
 
+			# The set of target names to process, or nil if no targets were specified.
+			# @returns [Set | Nil] The set of target names.
 			def targets
 				if @targets and @targets.any?
 					Set.new(@targets)
 				end
 			end
 
+			# Get the selection for the given context.
+			# @parameter context [Context] The project context.
+			# @returns [Select] The selection.
 			def selection(context)
 				if targets = self.targets
 					context.select(targets)
@@ -26,6 +32,7 @@ def selection(context)
 				end
 			end
 
+			# Execute the selection command.
 			def call
 				context = parent.context
 

lib/teapot/command/status.rb

@@ -9,9 +9,13 @@
 
 module Teapot
 	module Command
+		# A command to show git status of packages.
 		class Status < Selection
 			self.description = "List the git status of the specified package(s)."
 
+			# Create a terminal with custom styles for colorizing git status information.
+			# @parameter output [IO] The output stream.
+			# @returns [Console::Terminal] The configured terminal.
 			def terminal(output = $stdout)
 				Console::Terminal.for(output).tap do |terminal|
 					terminal[:worktree_new] = terminal.style(:green)
@@ -20,13 +24,18 @@ def terminal(output = $stdout)
 				end
 			end
 
+			# Open the git repository for a package, or return nil if the package doesn't have a repository yet.
+			# @parameter package [Package] The package.
+			# @returns [Rugged::Repository | Nil] The repository or nil.
 			def repository_for(package)
 				Rugged::Repository.new(package.path.to_s)
 			rescue Rugged::RepositoryError
 				# In some cases, a repository might not exist yet, so just skip the package.
 				nil
 			end
 
+			# Process and display the selection.
+			# @parameter selection [Select] The selection to process.
 			def process(selection)
 				context = selection.context
 				terminal = self.terminal