io-endpoint 0.15.2 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ab97a46f319ca04819bf0c53b225163977979f70242a77d84f09f2a4da438be
-  data.tar.gz: 396ba42209012cc921b2ecff5ef51eedcba214f215d7b4fcb62d4cb1f52347ea
+  metadata.gz: 99b21a2454e10904ebbf717bf4c1f5dcc337db1a50c88cefea5ef25116759ef2
+  data.tar.gz: 4f789220815ddc651cf8397697e30924660c231bebcdb2375f14eac1785fed39
 SHA512:
-  metadata.gz: 77457ee3835cc1daa48a72ad6e025e855061dadbafbbd154090e81bf2854b2e96abe0a70f82eef58eb1893eaf1e968f668d6e58485879d2216ad0680a3a4263b
-  data.tar.gz: 0f01d192468b9e6c38ec6e410086674bfe7a6ff96622ab82cd8739b5627e02c055bfbb193dbcd806fc4a87bea7880bf234c1a6c197e0a4f2d426dc66a49352f5
+  metadata.gz: 4c1720d279b749cd199455eb42ef4fe023a62287100230734d989b6dd8a944b8585c5f5565fa5899aa30b8563ae6350e938632e0c7b2a0b816d80f7273ddf81a
+  data.tar.gz: 06baff00190678e64cd396e6ac90e4f6a3e136295fabbaa92b6e7ab7d3894ab9345e084430745d6e0ba0633af7ed240a8478009fafc12134d3886aad4c642e05

data/context/getting-started.md

@@ -0,0 +1,113 @@
+# Getting Started
+
+This guide explains how to get started with `io-endpoint`, a library that provides a separation of concerns interface for network I/O endpoints.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add io-endpoint
+~~~
+
+## Core Concepts
+
+`io-endpoint` provides a unified interface for working with network endpoints, allowing you to write code that is agnostic to the underlying transport mechanism (TCP, UDP, UNIX sockets, SSL/TLS). This separation of concerns makes it easier to:
+
+- **Write transport-agnostic code**: Your application logic doesn't need to know whether it's using TCP, UDP, or UNIX sockets.
+- **Test with different transports**: Easily swap between transports during testing.
+- **Handle multiple addresses**: Automatically handle IPv4 and IPv6 addresses.
+- **Compose endpoints**: Combine multiple endpoints for failover or load distribution.
+
+The library centers around the {ruby IO::Endpoint::Generic} class, which represents a network endpoint that can be bound (for servers) or connected to (for clients). Different endpoint types handle different scenarios:
+
+- {ruby IO::Endpoint::HostEndpoint} - Resolves hostnames to addresses (e.g., "localhost:8080")
+- {ruby IO::Endpoint::AddressEndpoint} - Works with specific network addresses
+- {ruby IO::Endpoint::UNIXEndpoint} - Handles UNIX domain sockets
+- {ruby IO::Endpoint::SSLEndpoint} - Wraps endpoints with SSL/TLS encryption
+- {ruby IO::Endpoint::CompositeEndpoint} - Combines multiple endpoints
+
+## Usage
+
+### Creating a TCP Server
+
+When you need to create a server that listens on a specific port, you can use {ruby IO::Endpoint.tcp} to create a TCP endpoint:
+
+```ruby
+require "io/endpoint"
+
+# Create a TCP endpoint listening on localhost port 8080:
+endpoint = IO::Endpoint.tcp("localhost", 8080)
+
+# Bind to the endpoint and accept connections:
+endpoint.bind do |server|
+	# The server socket is automatically closed when the block exits
+	server.listen(10)
+	
+	loop do
+		client, address = server.accept
+		# Handle the client connection
+		client.close
+	end
+end
+```
+
+### Creating a TCP Client
+
+To connect to a remote server, use the `connect` method:
+
+```ruby
+require "io/endpoint"
+
+# Create a TCP endpoint for the remote server:
+endpoint = IO::Endpoint.tcp("example.com", 80)
+
+# Connect to the server:
+endpoint.connect do |socket|
+	# The socket is automatically closed when the block exits
+	socket.write("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")
+	response = socket.read
+	puts response
+end
+```
+
+### Using UNIX Domain Sockets
+
+For inter-process communication on the same machine, UNIX domain sockets provide better performance than TCP:
+
+```ruby
+require "io/endpoint"
+
+# Create a UNIX socket endpoint:
+endpoint = IO::Endpoint.unix("/tmp/myapp.sock")
+
+# Bind to the socket:
+endpoint.bind do |server|
+	server.listen(10)
+	
+	loop do
+		client, address = server.accept
+		# Handle the client connection
+		client.close
+	end
+end
+```
+
+### Using SSL/TLS
+
+To add encryption to your connections, wrap a TCP endpoint with SSL:
+
+```ruby
+require "io/endpoint"
+
+# Create an SSL endpoint:
+endpoint = IO::Endpoint.ssl("example.com", 443, hostname: "example.com")
+
+# Connect with SSL encryption:
+endpoint.connect do |socket|
+	# The socket is automatically encrypted
+	socket.write("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")
+	response = socket.read
+	puts response
+end
+```

data/context/index.yaml

@@ -0,0 +1,17 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Provides a separation of concerns interface for IO endpoints.
+metadata:
+  documentation_uri: https://socketry.github.io/io-endpoint
+  source_code_uri: https://github.com/socketry/io-endpoint.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to get started with `io-endpoint`, a library
+    that provides a separation of concerns interface for network I/O endpoints.
+- path: named-endpoints.md
+  title: Named Endpoints
+  description: This guide explains how to use `IO::Endpoint::NamedEndpoints` to manage
+    multiple endpoints by name, enabling scenarios like running the same application
+    on different protocols or ports.

data/context/named-endpoints.md

@@ -0,0 +1,140 @@
+# Named Endpoints
+
+This guide explains how to use `IO::Endpoint::NamedEndpoints` to manage multiple endpoints by name, enabling scenarios like running the same application on different protocols or ports.
+
+## Overview
+
+`NamedEndpoints` is a collection of endpoints that can be accessed by symbolic names. Unlike {ruby IO::Endpoint::CompositeEndpoint}, which treats endpoints as an ordered list for failover, `NamedEndpoints` allows you to:
+
+- **Access endpoints by name**: Use symbolic keys like `:http1` or `:http2` instead of array indices.
+- **Run multiple configurations**: Serve the same application on different protocols, ports, or transports simultaneously.
+- **Iterate over endpoints**: Process all endpoints while maintaining their names for configuration lookup.
+
+## When to Use NamedEndpoints
+
+Use `NamedEndpoints` when you need to:
+
+- Run the same server application on multiple endpoints with different configurations (e.g., HTTP/1 and HTTP/2).
+- Access endpoints by symbolic names rather than position.
+- Bind multiple endpoints and create servers for each one.
+- Manage a collection of endpoints where each has a specific role or configuration.
+
+If you need failover behavior (trying endpoints in order until one succeeds), use {ruby IO::Endpoint::CompositeEndpoint} instead.
+
+## Creating Named Endpoints
+
+### Using the Constructor
+
+Create a `NamedEndpoints` instance by passing a hash of endpoints:
+
+```ruby
+require "io/endpoint"
+
+http1_endpoint = IO::Endpoint.tcp("localhost", 8080)
+http2_endpoint = IO::Endpoint.tcp("localhost", 8090)
+
+named = IO::Endpoint::NamedEndpoints.new(
+	http1: http1_endpoint,
+	http2: http2_endpoint
+)
+```
+
+### Using the Factory Method
+
+The `IO::Endpoint.named` factory method provides a convenient way to create named endpoints:
+
+```ruby
+require "io/endpoint"
+
+named = IO::Endpoint.named(
+	http1: IO::Endpoint.tcp("localhost", 8080),
+	http2: IO::Endpoint.tcp("localhost", 8090),
+	https: IO::Endpoint.ssl("localhost", 8443)
+)
+```
+
+## Accessing Endpoints
+
+Access endpoints by their names using the `[]` operator:
+
+```ruby
+named = IO::Endpoint.named(
+	http1: IO::Endpoint.tcp("localhost", 8080),
+	http2: IO::Endpoint.tcp("localhost", 8090)
+)
+
+# Access by name
+http1 = named[:http1]
+http2 = named[:http2]
+
+# Returns nil if not found
+missing = named[:nonexistent]  # => nil
+```
+
+## Iterating Over Endpoints
+
+### Using `each`
+
+The `each` method yields both the name and endpoint:
+
+```ruby
+named = IO::Endpoint.named(
+	http1: IO::Endpoint.tcp("localhost", 8080),
+	http2: IO::Endpoint.tcp("localhost", 8090)
+)
+
+named.each do |name, endpoint|
+	puts "Endpoint #{name} is bound to #{endpoint}"
+end
+```
+
+To map over endpoint values, use `endpoints.values.map`:
+
+```ruby
+protocols = named.endpoints.values.map do |endpoint|
+	endpoint.protocol.to_s
+end
+
+# => ["HTTP1", "HTTP2"]
+```
+
+## Binding Endpoints
+
+To bind endpoints, iterate over the collection and bind each endpoint individually, or use the `bound` method to create a new collection with all endpoints bound.
+
+The `bound` method creates a new `NamedEndpoints` instance where all endpoints are bound:
+
+```ruby
+named = IO::Endpoint.named(
+	http1: IO::Endpoint.tcp("localhost", 8080),
+	http2: IO::Endpoint.tcp("localhost", 8090)
+)
+
+bound_named = named.bound(reuse_address: true)
+
+# All endpoints are now bound
+bound_named.each do |name, bound_endpoint|
+	server = bound_endpoint.sockets.first
+	server.listen(10)
+end
+```
+
+## Connecting to Endpoints
+
+To connect to a specific endpoint, access it by name and call `connect` on that endpoint:
+
+```ruby
+named = IO::Endpoint.named(
+	primary: IO::Endpoint.tcp("server1.example.com", 80),
+	secondary: IO::Endpoint.tcp("server2.example.com", 80)
+)
+
+# Connect to a specific endpoint by name
+named[:primary].connect do |socket|
+	socket.write("GET / HTTP/1.1\r\n\r\n")
+	response = socket.read
+	puts response
+end
+```
+
+If you need failover behavior (trying endpoints in order until one succeeds), use {ruby IO::Endpoint::CompositeEndpoint} instead.

data/lib/io/endpoint/address_endpoint.rb

@@ -9,13 +9,19 @@ require_relative "generic"
 require_relative "wrapper"
 
 module IO::Endpoint
+	# Represents an endpoint for a specific network address.
 	class AddressEndpoint < Generic
+		# Initialize a new address endpoint.
+		# @parameter address [Address] The network address for this endpoint.
+		# @parameter options [Hash] Additional options to pass to the parent class.
 		def initialize(address, **options)
 			super(**options)
 			
 			@address = address
 		end
 		
+		# Get a string representation of the endpoint.
+		# @returns [String] A string representation of the endpoint address.
 		def to_s
 			case @address.afamily
 			when Socket::AF_INET
@@ -27,22 +33,25 @@ module IO::Endpoint
 			end
 		end
 		
+		# Get a detailed string representation of the endpoint.
+		# @returns [String] A detailed string representation including the address.
 		def inspect
 			"\#<#{self.class} address=#{@address.inspect}>"
 		end
 		
+		# @attribute [Address] The network address for this endpoint.
 		attr :address
 		
 		# Bind a socket to the given address. If a block is given, the socket will be automatically closed when the block exits.
-		# @yield {|socket| ...}	An optional block which will be passed the socket.
-		#   @parameter socket [Socket] The socket which has been bound.
-		# @return [Array(Socket)] the bound socket
+		# @yields {|socket| ...} If a block is given, yields the bound socket.
+		# 	@parameter socket [Socket] The socket which has been bound.
+		# @returns [Array(Socket)] the bound socket
 		def bind(wrapper = self.wrapper, &block)
 			[wrapper.bind(@address, **@options, &block)]
 		end
 		
 		# Connects a socket to the given address. If a block is given, the socket will be automatically closed when the block exits.
-		# @return [Socket] the connected socket
+		# @returns [Socket] the connected socket
 		def connect(wrapper = self.wrapper, &block)
 			wrapper.connect(@address, **@options, &block)
 		end

data/lib/io/endpoint/bound_endpoint.rb

@@ -8,7 +8,13 @@ require_relative "composite_endpoint"
 require_relative "address_endpoint"
 
 module IO::Endpoint
+	# Represents an endpoint that has been bound to one or more sockets.
 	class BoundEndpoint < Generic
+		# Create a bound endpoint from an existing endpoint.
+		# @parameter endpoint [Generic] The endpoint to bind.
+		# @option backlog [Integer] The maximum length of the queue of pending connections.
+		# @option close_on_exec [Boolean] Whether to close sockets on exec.
+		# @returns [BoundEndpoint] A new bound endpoint instance.
 		def self.bound(endpoint, backlog: Socket::SOMAXCONN, close_on_exec: false)
 			sockets = endpoint.bind
 			
@@ -19,6 +25,10 @@ module IO::Endpoint
 			return self.new(endpoint, sockets, **endpoint.options)
 		end
 		
+		# Initialize a new bound endpoint.
+		# @parameter endpoint [Generic] The original endpoint that was bound.
+		# @parameter sockets [Array(Socket)] The sockets that were bound.
+		# @parameter options [Hash] Additional options to pass to the parent class.
 		def initialize(endpoint, sockets, **options)
 			super(**options)
 			
@@ -26,7 +36,9 @@ module IO::Endpoint
 			@sockets = sockets
 		end
 		
+		# @attribute [Generic] The original endpoint that was bound.
 		attr :endpoint
+		# @attribute [Array(Socket)] The sockets that were bound.
 		attr :sockets
 		
 		# A endpoint for the local end of the bound socket.
@@ -49,19 +61,29 @@ module IO::Endpoint
 			return CompositeEndpoint.new(endpoints)
 		end
 		
+		# Close all bound sockets.
 		def close
 			@sockets.each(&:close)
 			@sockets.clear
 		end
 		
+		# Get a string representation of the bound endpoint.
+		# @returns [String] A string representation of the bound endpoint.
 		def to_s
 			"bound:#{@endpoint}"
 		end
 		
+		# Get a detailed string representation of the bound endpoint.
+		# @returns [String] A detailed string representation including socket count.
 		def inspect
 			"\#<#{self.class} #{@sockets.size} bound sockets for #{@endpoint}>"
 		end
 		
+		# Bind the endpoint using the given wrapper.
+		# @parameter wrapper [Wrapper] The wrapper to use for binding.
+		# @yields {|socket| ...} If a block is given, yields each bound socket.
+		# 	@parameter socket [Socket] A bound socket.
+		# @returns [Array(Socket)] An array of bound sockets.
 		def bind(wrapper = self.wrapper, &block)
 			@sockets.map do |server|
 				if block_given?
@@ -76,6 +98,9 @@ module IO::Endpoint
 	end
 	
 	class Generic
+		# Create a bound endpoint from this endpoint.
+		# @parameter options [Hash] Options to pass to {BoundEndpoint.bound}.
+		# @returns [BoundEndpoint] A new bound endpoint instance.
 		def bound(**options)
 			BoundEndpoint.bound(self, **options)
 		end

data/lib/io/endpoint/composite_endpoint.rb

@@ -8,6 +8,9 @@ require_relative "generic"
 module IO::Endpoint
 	# A composite endpoint is a collection of endpoints that are used in order.
 	class CompositeEndpoint < Generic
+		# Initialize a new composite endpoint.
+		# @parameter endpoints [Array(Generic)] The endpoints to compose.
+		# @parameter options [Hash] Additional options to pass to the parent class and propagate to endpoints.
 		def initialize(endpoints, **options)
 			super(**options)
 			
@@ -19,18 +22,26 @@ module IO::Endpoint
 			@endpoints = endpoints
 		end
 		
+		# Get a string representation of the composite endpoint.
+		# @returns [String] A string representation listing all endpoints.
 		def to_s
 			"composite:#{@endpoints.join(",")}"
 		end
 		
+		# Get a detailed string representation of the composite endpoint.
+		# @returns [String] A detailed string representation including all endpoints.
 		def inspect
 			"\#<#{self.class} endpoints=#{@endpoints}>"
 		end
 		
+		# Create a new composite endpoint with merged options.
+		# @parameter options [Hash] Additional options to merge with existing options.
+		# @returns [CompositeEndpoint] A new composite endpoint instance with merged options.
 		def with(**options)
 			self.class.new(endpoints.map{|endpoint| endpoint.with(**options)}, **@options.merge(options))
 		end
 		
+		# @attribute [Array(Generic)] The endpoints in this composite endpoint.
 		attr :endpoints
 		
 		# The number of endpoints in the composite endpoint.
@@ -38,12 +49,21 @@ module IO::Endpoint
 			@endpoints.size
 		end
 		
+		# Enumerate all endpoints in the composite endpoint.
+		# @yields {|endpoint| ...} For each endpoint in the composite, yields it.
+		# 	@parameter endpoint [Generic] An endpoint in the composite.
 		def each(&block)
 			@endpoints.each do |endpoint|
 				endpoint.each(&block)
 			end
 		end
 		
+		# Connect to the first endpoint that succeeds.
+		# @parameter wrapper [Wrapper] The wrapper to use for connecting.
+		# @yields {|socket| ...} If a block is given, yields the connected socket from the first successful endpoint.
+		# 	@parameter socket [Socket] The connected socket.
+		# @returns [Socket] The connected socket.
+		# @raises [Exception] If all endpoints fail to connect, raises the last error encountered.
 		def connect(wrapper = self.wrapper, &block)
 			last_error = nil
 			
@@ -57,6 +77,11 @@ module IO::Endpoint
 			raise last_error
 		end
 		
+		# Bind all endpoints in the composite.
+		# @parameter wrapper [Wrapper] The wrapper to use for binding.
+		# @yields {|socket| ...} For each endpoint that is bound, yields the bound socket.
+		# 	@parameter socket [Socket] A bound socket.
+		# @returns [Array(Socket)] An array of bound sockets if no block is given.
 		def bind(wrapper = self.wrapper, &block)
 			if block_given?
 				@endpoints.each do |endpoint|
@@ -68,6 +93,10 @@ module IO::Endpoint
 		end
 	end
 	
+	# Create a composite endpoint from multiple endpoints.
+	# @parameter endpoints [Array(Generic)] The endpoints to compose.
+	# @parameter options [Hash] Additional options to pass to the composite endpoint.
+	# @returns [CompositeEndpoint] A new composite endpoint instance.
 	def self.composite(*endpoints, **options)
 		CompositeEndpoint.new(endpoints, **options)
 	end

data/lib/io/endpoint/connected_endpoint.rb

@@ -10,7 +10,12 @@ require_relative "socket_endpoint"
 require "openssl"
 
 module IO::Endpoint
+	# Represents an endpoint that has been connected to a socket.
 	class ConnectedEndpoint < Generic
+		# Create a connected endpoint from an existing endpoint.
+		# @parameter endpoint [Generic] The endpoint to connect.
+		# @option close_on_exec [Boolean] Whether to close the socket on exec.
+		# @returns [ConnectedEndpoint] A new connected endpoint instance.
 		def self.connected(endpoint, close_on_exec: false)
 			socket = endpoint.connect
 			
@@ -19,6 +24,10 @@ module IO::Endpoint
 			return self.new(endpoint, socket, **endpoint.options)
 		end
 		
+		# Initialize a new connected endpoint.
+		# @parameter endpoint [Generic] The original endpoint that was connected.
+		# @parameter socket [Socket] The socket that was connected.
+		# @parameter options [Hash] Additional options to pass to the parent class.
 		def initialize(endpoint, socket, **options)
 			super(**options)
 			
@@ -26,7 +35,9 @@ module IO::Endpoint
 			@socket = socket
 		end
 		
+		# @attribute [Generic] The original endpoint that was connected.
 		attr :endpoint
+		# @attribute [Socket] The socket that was connected.
 		attr :socket
 		
 		# A endpoint for the local end of the bound socket.
@@ -41,6 +52,11 @@ module IO::Endpoint
 			AddressEndpoint.new(socket.to_io.remote_address, **options)
 		end
 		
+		# Connect using the already connected socket.
+		# @parameter wrapper [Wrapper] The wrapper to use (unused, socket is already connected).
+		# @yields {|socket| ...} If a block is given, yields the connected socket.
+		# 	@parameter socket [Socket] The connected socket.
+		# @returns [Socket] The connected socket or a duplicate if no block is given.
 		def connect(wrapper = self.wrapper, &block)
 			if block_given?
 				yield @socket
@@ -49,6 +65,7 @@ module IO::Endpoint
 			end
 		end
 		
+		# Close the connected socket.
 		def close
 			if @socket
 				@socket.close
@@ -56,16 +73,23 @@ module IO::Endpoint
 			end
 		end
 		
+		# Get a string representation of the connected endpoint.
+		# @returns [String] A string representation of the connected endpoint.
 		def to_s
 			"connected:#{@endpoint}"
 		end
 		
+		# Get a detailed string representation of the connected endpoint.
+		# @returns [String] A detailed string representation including the socket.
 		def inspect
 			"\#<#{self.class} #{@socket} connected for #{@endpoint}>"
 		end
 	end
-		
+	
 	class Generic
+		# Create a connected endpoint from this endpoint.
+		# @parameter options [Hash] Options to pass to {ConnectedEndpoint.connected}.
+		# @returns [ConnectedEndpoint] A new connected endpoint instance.
 		def connected(**options)
 			ConnectedEndpoint.connected(self, **options)
 		end

data/lib/io/endpoint/generic.rb

@@ -12,10 +12,15 @@ module IO::Endpoint
 	
 	# Endpoints represent a way of connecting or binding to an address.
 	class Generic
+		# Initialize a new generic endpoint.
+		# @parameter options [Hash] Configuration options for the endpoint.
 		def initialize(**options)
 			@options = options.freeze
 		end
 		
+		# Create a new endpoint with merged options.
+		# @parameter options [Hash] Additional options to merge with existing options.
+		# @returns [Generic] A new endpoint instance with merged options.
 		def with(**options)
 			dup = self.dup
 			
@@ -26,43 +31,43 @@ module IO::Endpoint
 		
 		attr_accessor :options
 		
-		# @return [String] The hostname of the bound socket.
+		# @returns [String] The hostname of the bound socket.
 		def hostname
 			@options[:hostname]
 		end
 		
 		# If `SO_REUSEPORT` is enabled on a socket, the socket can be successfully bound even if there are existing sockets bound to the same address, as long as all prior bound sockets also had `SO_REUSEPORT` set before they were bound.
-		# @return [Boolean, nil] The value for `SO_REUSEPORT`.
+		# @returns [Boolean, nil] The value for `SO_REUSEPORT`.
 		def reuse_port?
 			@options[:reuse_port]
 		end
 		
 		# If `SO_REUSEADDR` is enabled on a socket prior to binding it, the socket can be successfully bound unless there is a conflict with another socket bound to exactly the same combination of source address and port. Additionally, when set, binding a socket to the address of an existing socket in `TIME_WAIT` is not an error.
-		# @return [Boolean] The value for `SO_REUSEADDR`.
+		# @returns [Boolean] The value for `SO_REUSEADDR`.
 		def reuse_address?
 			@options[:reuse_address]
 		end
 		
 		# Controls SO_LINGER. The amount of time the socket will stay in the `TIME_WAIT` state after being closed.
-		# @return [Integer, nil] The value for SO_LINGER.
+		# @returns [Integer, nil] The value for SO_LINGER.
 		def linger
 			@options[:linger]
 		end
 		
-		# @return [Numeric] The default timeout for socket operations.
+		# @returns [Numeric] The default timeout for socket operations.
 		def timeout
 			@options[:timeout]
 		end
 		
-		# @return [Address] the address to bind to before connecting.
+		# @returns [Address] the address to bind to before connecting.
 		def local_address
 			@options[:local_address]
 		end
 		
 		# Bind a socket to the given address. If a block is given, the socket will be automatically closed when the block exits.
 		# @parameter wrapper [Wrapper] The wrapper to use for binding.
-		# @yields {|socket| ...}	An optional block which will be passed the socket.
-		#   @parameter socket [Socket] The socket which has been bound.
+		# @yields {|socket| ...} If a block is given, yields the bound socket.
+		# 	@parameter socket [Socket] The socket which has been bound.
 		# @returns [Array(Socket)] the bound socket
 		def bind(wrapper = self.wrapper, &block)
 			raise NotImplementedError
@@ -70,14 +75,15 @@ module IO::Endpoint
 		
 		# Connects a socket to the given address. If a block is given, the socket will be automatically closed when the block exits.
 		# @parameter wrapper [Wrapper] The wrapper to use for connecting.
-		# @return [Socket] the connected socket
+		# @returns [Socket] the connected socket
 		def connect(wrapper = self.wrapper, &block)
 			raise NotImplementedError
 		end
 		
 		# Bind and accept connections on the given address.
 		# @parameter wrapper [Wrapper] The wrapper to use for accepting connections.
-		# @yields [Socket] The accepted socket.
+		# @yields {|socket| ...} For each accepted connection, yields the socket.
+		# 	@parameter socket [Socket] The accepted socket.
 		def accept(wrapper = self.wrapper, &block)
 			bind(wrapper) do |server|
 				wrapper.accept(server, **@options, &block)
@@ -85,7 +91,7 @@ module IO::Endpoint
 		end
 		
 		# Enumerate all discrete paths as endpoints.
-		# @yields {|endpoint| ...} A block which will be passed each endpoint.
+		# @yields {|endpoint| ...} For each endpoint, yields it.
 		# 	@parameter endpoint [Endpoint] The endpoint.
 		def each
 			return to_enum unless block_given?
@@ -97,8 +103,8 @@ module IO::Endpoint
 		#
 		# You should not use untrusted input as it may execute arbitrary code.
 		#
-		# @param string [String] URI as string. Scheme will decide implementation used.
-		# @param options keyword arguments passed through to {#initialize}
+		# @parameter string [String] URI as string. Scheme will decide implementation used.
+		# @parameter options keyword arguments passed through to {#initialize}
 		#
 		# @see Endpoint.ssl ssl - invoked when parsing a URL with the ssl scheme "ssl://127.0.0.1"
 		# @see Endpoint.tcp tcp - invoked when parsing a URL with the tcp scheme: "tcp://127.0.0.1"