Add documentation.

Author: ioquatix

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,44 +4,8 @@ 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
-```
-
 ## Contributing
 
 We welcome contributions to this project.