Add documentation.

Author: ioquatix

async-await.gemspec

@@ -16,6 +16,7 @@ Gem::Specification.new do |spec|
 	spec.homepage = "https://github.com/socketry/async-await"
 
 	spec.metadata = {
+		"documentation_uri" => "https://socketry.github.io/async-await/",
 		"source_code_uri" => "https://github.com/socketry/async-await.git",
 	}
 

bake.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+# Update the project documentation with the new version number.
+#
+# @parameter version [String] The new version number.
+def after_gem_release_version_increment(version)
+	context["releases:update"].call(version)
+	context["utopia:project:readme:update"].call
+end

gems.rb

@@ -10,6 +10,9 @@
 group :maintenance, optional: true do
 	gem "bake-modernize"
 	gem "bake-gem"
+	gem "bake-releases"
+	
+	gem "utopia-project"
 end
 
 group :test do

guides/getting-started/readme.md

@@ -0,0 +1,78 @@
+# Getting Started
+
+This guide explains how to use `async-await` for implementing some common concurrency patterns.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add async-await
+~~~
+
+## Usage
+
+### "async" Keyword
+
+This gem provides {ruby Async::Await} which introduces the `async` keyword. This keyword is used to define asynchronous methods. The method will return an `Async::Task` object, which can be waited on to get the result.
+
+``` ruby
+require 'async/await'
+
+class Coop
+	include Async::Await
+	
+	async def count_chickens(area_name)
+		3.times do |i|
+			sleep rand
+			
+			puts "Found a chicken in the #{area_name}!"
+		end
+	end
+
+	async def count_all_chickens
+		# These methods all run at the same time.
+		count_chickens("garden")
+		count_chickens("house")
+		
+		# We wait for the result
+		count_chickens("tree").wait
+	end
+end
+
+coop = Coop.new
+coop.count_all_chickens
+```
+
+This interface was originally designed as a joke, but may be useful in some limited contexts. It is not recommended for general use.
+
+### Enumerable
+
+This gem provides {ruby Async::Await::Enumerable} which adds async support to the `Enumerable` module. This allows you to use concurrency in a more functional style.
+
+``` ruby
+require "async/await/enumerable"
+
+[1, 2, 3].async_each do |i|
+	sleep rand
+	puts i
+end
+```
+
+This will run the block for each element in the array concurrently.
+
+#### Using a Semaphore
+
+In order to prevent unlimited concurrency, you can use a semaphore to limit the number of concurrent tasks. This is useful when you want to limit the number of concurrent tasks to a specific number.
+
+``` ruby
+require "async/await/enumerable"
+require "async/semaphore"
+
+semaphore = Async::Semaphore.new(2)
+
+[1, 2, 3].async_each(parent: semaphore) do |i|
+	sleep rand
+	puts i
+end
+```

lib/async/await.rb

@@ -5,12 +5,18 @@
 
 require_relative "await/version"
 
+# @namespace
 module Async
+	# Provide a way to wrap methods so that they can be run synchronously or asynchronously in an event loop.
 	module Await
+		# A hook that is called when the module is included in a class in order to provide the class with the methods defined in this module.
 		def self.included(klass)
 			klass.extend(self)
 		end
 
+		# Wrap the method with the given name in a block that will run the method synchronously in an event loop.
+		#
+		# @parameter name [Symbol] The name of the method to wrap.
 		def sync(name)
 			original_method = instance_method(name)
 
@@ -25,8 +31,13 @@ def sync(name)
 					end.wait
 				end
 			end
+			
+			return name
 		end
 
+		# Wrap the method with the given name in a block that will run the method asynchronously in an event loop.
+		#
+		# @parameter name [Symbol] The name of the method to wrap.
 		def async(name)
 			original_method = instance_method(name)
 
@@ -37,6 +48,8 @@ def async(name)
 					original_method.bind(self).call(*arguments, &block)
 				end
 			end
+			
+			return name
 		end
 	end
 end

lib/async/await/enumerable.rb

@@ -7,7 +7,12 @@
 
 module Async
 	module Await
+		# Provide asynchronous methods for enumerables.
 		module Enumerable
+			# This method is used to map the elements of an enumerable collection asynchronously.
+			#
+			# @parameter parent [Interface(:async)] The parent to use for creating new tasks.
+			# @yields {|item| ...} The block to execute for each element in the collection.
 			def async_map(parent: nil, &block)
 				Sync do |task|
 					parent ||= task
@@ -20,6 +25,11 @@ def async_map(parent: nil, &block)
 				end
 			end
 
+			# This method is used to iterate over the elements of an enumerable collection asynchronously.
+			#
+			# @parameter parent [Interface(:async)] The parent to use for creating new tasks.
+			# @yields {|item| ...} The block to execute for each element in the collection.
+			# @return [self] The original enumerable collection.
 			def async_each(parent: nil, &block)
 				Sync do |task|
 					parent ||= task

readme.md

@@ -4,43 +4,11 @@ Implements the async/await pattern for Ruby using [async](https://github.com/soc
 
 [![Development Status](https://github.com/socketry/async-await/workflows/Test/badge.svg)](https://github.com/socketry/async-await/actions?workflow=Test)
 
-## Installation
-
-``` shell
-bundle add async-await
-```
-
 ## Usage
 
-In any asynchronous context (e.g. a reactor), simply use the `await` function like so:
-
-``` ruby
-require 'async/await'
-
-class Coop
-	include Async::Await
-	
-	async def count_chickens(area_name)
-		3.times do |i|
-			sleep rand
-			
-			puts "Found a chicken in the #{area_name}!"
-		end
-	end
-
-	async def count_all_chickens
-		# These methods all run at the same time.
-		count_chickens("garden")
-		count_chickens("house")
-		
-		# We wait for the result
-		count_chickens("tree").wait
-	end
-end
-
-coop = Coop.new
-coop.count_all_chickens
-```
+Please see the [project documentation](https://socketry.github.io/async-await/) for more details.
+
+  - [Getting Started](https://socketry.github.io/async-await/guides/getting-started/index) - This guide explains how to use `async-await` for implementing some common concurrency patterns.
 
 ## Contributing