100% documentation coverage.

Author: ioquatix

lib/process/metrics/command.rb

@@ -7,7 +7,10 @@
 
 module Process
 	module Metrics
+		# @namespace
 		module Command
+			# Call the default command (Top).
+			# @parameter arguments [Array] Command-line arguments to pass through.
 			def self.call(*arguments)
 				Top.call(*arguments)
 			end

lib/process/metrics/command/summary.rb

@@ -12,6 +12,7 @@
 module Process
 	module Metrics
 		module Command
+			# Helper module for rendering horizontal progress bars using Unicode block characters.
 			module Bar
 				BLOCK = [
 					" ",
@@ -25,6 +26,10 @@ module Bar
 					"█",
 				]
 
+				# Format a fractional value as a horizontal bar.
+				# @parameter value [Float] A value between 0.0 and 1.0 representing the fill level.
+				# @parameter width [Integer] The width of the bar in characters.
+				# @returns [String] A string of Unicode block characters representing the filled bar.
 				def self.format(value, width)
 					blocks = width * value
 					full_blocks = blocks.floor
@@ -38,6 +43,7 @@ def self.format(value, width)
 				end
 			end
 
+			# Command that displays a formatted summary of memory usage statistics for processes.
 			class Summary < Samovar::Command
 				self.description = "Display a summary of memory usage statistics."
 
@@ -48,6 +54,8 @@ class Summary < Samovar::Command
 					option "--total-memory <integer>", "Set the total memory relative to the usage (MiB).", type: Integer
 				end
 
+				# Get the configured terminal for styled output.
+				# @returns [Console::Terminal] A terminal object with color/style definitions.
 				def terminal
 					terminal = Console::Terminal.for($stdout)
 
@@ -62,6 +70,9 @@ def terminal
 					return terminal
 				end
 
+				# Format a processor utilization percentage with color-coded bar.
+				# @parameter value [Float] The CPU utilization percentage (0.0-100.0).
+				# @parameter terminal [Console::Terminal] The terminal to output styled text.
 				def format_processor_utilization(value, terminal)
 					if value > 80.0
 						intensity = :high
@@ -78,6 +89,10 @@ def format_processor_utilization(value, terminal)
 
 				UNITS = ["KiB", "MiB", "GiB"]
 
+				# Format a memory size value in human-readable units.
+				# @parameter value [Numeric] The size value in kilobytes.
+				# @parameter units [Array(String)] The unit labels to use for scaling.
+				# @returns [String] A formatted string with value and unit (e.g., "512KiB", "1.5MiB").
 				def format_size(value, units: UNITS)
 					unit = 0
 
@@ -89,6 +104,10 @@ def format_size(value, units: UNITS)
 					return "#{value.round(unit)}#{units[unit]}"
 				end
 
+				# Format a memory value with a horizontal bar showing utilization relative to total.
+				# @parameter value [Numeric] The memory value in kilobytes.
+				# @parameter total [Numeric] The total memory available in kilobytes.
+				# @parameter terminal [Console::Terminal] The terminal to output styled text.
 				def format_memory(value, total, terminal)
 					if value > (total * 0.8)
 						intensity = :high
@@ -103,6 +122,8 @@ def format_memory(value, total, terminal)
 					terminal.print(formatted, intensity, "[", Bar.format(value / total.to_f, 60), "]", :reset)
 				end
 
+				# Get the total memory to use for percentage calculations.
+				# @returns [Integer] Total memory in kilobytes.
 				def total_memory
 					if total_memory = @options[:total_memory]
 						return total_memory * 1024
@@ -111,6 +132,7 @@ def total_memory
 					end
 				end
 
+				# Execute the summary command, capturing and displaying process metrics.
 				def call
 					# Validate required arguments: at least one of --pid or --ppid must be provided:
 					unless @options[:pid] || @options[:ppid]

lib/process/metrics/command/top.rb

@@ -11,6 +11,7 @@
 module Process
 	module Metrics
 		module Command
+			# Top-level command entry point for the process-metrics CLI.
 			class Top < Samovar::Command
 				self.description = "Collect memory usage statistics."
 
@@ -23,6 +24,7 @@ class Top < Samovar::Command
 					"summary" => Summary,
 				}, default: "summary"
 
+				# Execute the top command, dispatching to nested commands.
 				def call
 					if @options[:version]
 						puts "#{self.name} v#{VERSION}"

lib/process/metrics/general.rb

@@ -84,12 +84,20 @@ def total_size
 
 			alias memory_usage total_size
 
+			# Recursively expand a set of child PIDs into a collection.
+			# @parameter children [Array<Integer>] The list of child process IDs to expand.
+			# @parameter hierarchy [Hash<Integer, Array<Integer>>] The parent-to-children process hierarchy.
+			# @parameter pids [Set<Integer>] The set to populate with process IDs.
 			def self.expand_children(children, hierarchy, pids)
 				children.each do |pid|
 					self.expand(pid, hierarchy, pids)
 				end
 			end
 
+			# Recursively expand a process and its descendants into a collection.
+			# @parameter pid [Integer] The process ID to expand.
+			# @parameter hierarchy [Hash<Integer, Array<Integer>>] The parent-to-children process hierarchy.
+			# @parameter pids [Set<Integer>] The set to populate with process IDs.
 			def self.expand(pid, hierarchy, pids)
 				unless pids.include?(pid)
 					pids << pid
@@ -100,6 +108,9 @@ def self.expand(pid, hierarchy, pids)
 				end
 			end
 
+			# Build a parent-to-children process hierarchy from a set of processes.
+			# @parameter processes [Hash<Integer, General>] A hash mapping PIDs to General instances.
+			# @returns [Hash<Integer, Array<Integer>>] A hash mapping each parent PID to an array of child PIDs.
 			def self.build_tree(processes)
 				hierarchy = Hash.new{|h,k| h[k] = []}
 
@@ -112,6 +123,8 @@ def self.build_tree(processes)
 				return hierarchy
 			end
 
+			# Capture detailed memory metrics for each process in the given collection.
+			# @parameter processes [Hash<Integer, General>] A hash mapping PIDs to General instances.
 			def self.capture_memory(processes)
 				count = processes.size
 

lib/process/metrics/memory.rb

@@ -27,6 +27,8 @@ def unique_size
 				self.private_clean_size + self.private_dirty_size
 			end
 
+			# Create a zero-initialized Memory instance.
+			# @returns [Memory] A new Memory object with all fields set to zero.
 			def self.zero
 				self.new(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
 			end

lib/process/metrics/memory/darwin.rb

@@ -5,6 +5,7 @@
 
 module Process
 	module Metrics
+		# Darwin (macOS) implementation of memory metrics using vmmap.
 		class Memory::Darwin
 			VMMAP = "/usr/bin/vmmap"
 
@@ -25,7 +26,9 @@ def self.total_size
 				end
 			end
 
-			# Parse a size string into kilobytes.
+			# Parse a size string from vmmap output into kilobytes.
+			# @parameter string [String | Nil] The size string (e.g., "4K", "1.5M", "2G").
+			# @returns [Integer] The size in kilobytes.
 			def self.parse_size(string)
 				return 0 unless string
 
@@ -93,14 +96,22 @@ def self.capture(pid, count: 1, **options)
 
 		if Memory::Darwin.supported?
 			class << Memory
+				# Whether memory capture is supported on this platform.
+				# @returns [Boolean] True if vmmap is available.
 				def supported?
 					return true
 				end
 
+				# Get total system memory size.
+				# @returns [Integer] Total memory in kilobytes.
 				def total_size
 					return Memory::Darwin.total_size
 				end
 
+				# Capture memory metrics for a process.
+				# @parameter pid [Integer] The process ID.
+				# @parameter options [Hash] Additional options (e.g., count for proportional estimates).
+				# @returns [Memory] A Memory instance with captured metrics.
 				def capture(...)
 					return Memory::Darwin.capture(...)
 				end

lib/process/metrics/memory/linux.rb

@@ -5,8 +5,11 @@
 
 module Process
 	module Metrics
+		# Linux implementation of memory metrics using `/proc/[pid]/smaps` and `/proc/[pid]/stat`.
 		class Memory::Linux
-			# Extract minor/major page fault counters from /proc/[pid]/stat and assign to usage.
+			# Extract minor/major page fault counters from `/proc/[pid]/stat` and assign to usage.
+			# @parameter pid [Integer] The process ID.
+			# @parameter usage [Memory] The Memory instance to populate with fault counters.
 			def self.capture_faults(pid, usage)
 				begin
 					stat = File.read("/proc/#{pid}/stat")
@@ -116,14 +119,22 @@ def self.supported?
 
 		if Memory::Linux.supported?
 			class << Memory
+				# Whether memory capture is supported on this platform.
+				# @returns [Boolean] True if /proc/[pid]/smaps or smaps_rollup is readable.
 				def supported?
 					return true
 				end
 
+				# Get total system memory size.
+				# @returns [Integer] Total memory in kilobytes.
 				def total_size
 					return Memory::Linux.total_size
 				end
 
+				# Capture memory metrics for a process.
+				# @parameter pid [Integer] The process ID.
+				# @parameter options [Hash] Additional options.
+				# @returns [Memory] A Memory instance with captured metrics.
 				def capture(...)
 					return Memory::Linux.capture(...)
 				end

lib/process/metrics/version.rb

@@ -3,7 +3,9 @@
 # Released under the MIT License.
 # Copyright, 2019-2025, by Samuel Williams.
 
+# @namespace
 module Process
+	# @namespace
 	module Metrics
 		VERSION = "0.5.2"
 	end