From c7162e653d467b8f2c941f0cc674c768228ad5c3 Mon Sep 17 00:00:00 2001 From: Postmodern Date: Sun, 5 Feb 2023 23:25:39 -0800 Subject: [PATCH] Documentation improvements. (#22) --- README.md | 35 ++++++++++++++--------------- lib/async/dns/server.rb | 43 ++++++++++++++++++++++++++++-------- lib/async/dns/transaction.rb | 2 +- 3 files changed, 52 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index af3c748..27a8c52 100644 --- a/README.md +++ b/README.md @@ -25,14 +25,14 @@ Or install it yourself as: Here is a simple example showing how to use the resolver: ``` ruby - Async::Reactor.run do - resolver = Async::DNS::Resolver.new([[:udp, "8.8.8.8", 53], [:tcp, "8.8.8.8", 53]]) +Async::Reactor.run do + resolver = Async::DNS::Resolver.new([[:udp, "8.8.8.8", 53], [:tcp, "8.8.8.8", 53]]) - addresses = resolver.addresses_for("www.google.com.") + addresses = resolver.addresses_for("www.google.com.") - puts addresses.inspect - end - => [#, #, #, #, #, #, #, #, #, #, #, #, #, #, #, #] + puts addresses.inspect +end +# [#, #, #, #, #, #, #, #, #, #, #, #, #, #, #, #] ``` ### Server @@ -40,19 +40,18 @@ Here is a simple example showing how to use the resolver: Here is a simple example showing how to use the server: ``` ruby - require 'async/dns' - - class TestServer < Async::DNS::Server - def process(name, resource_class, transaction) - @resolver ||= Async::DNS::Resolver.new([[:udp, '8.8.8.8', 53], [:tcp, '8.8.8.8', 53]]) - - transaction.passthrough!(@resolver) - end +require 'async/dns' + +class TestServer < Async::DNS::Server + def process(name, resource_class, transaction) + @resolver ||= Async::DNS::Resolver.new([[:udp, '8.8.8.8', 53], [:tcp, '8.8.8.8', 53]]) + + transaction.passthrough!(@resolver) end - - server = TestServer.new([[:udp, '127.0.0.1', 2346]]) - - server.run +end + +server = TestServer.new([[:udp, '127.0.0.1', 2346]]) +server.run ``` Then to test you could use `dig` like so: diff --git a/lib/async/dns/server.rb b/lib/async/dns/server.rb index 7f42e39..e7267ba 100644 --- a/lib/async/dns/server.rb +++ b/lib/async/dns/server.rb @@ -24,30 +24,55 @@ require_relative 'transaction' module Async::DNS + # + # Base class for defining asynchronous DNS servers. + # + # ## Example + # + # require 'async/dns' + # + # class TestServer < Async::DNS::Server + # def process(name, resource_class, transaction) + # @resolver ||= Async::DNS::Resolver.new([[:udp, '8.8.8.8', 53], [:tcp, '8.8.8.8', 53]]) + # + # transaction.passthrough!(@resolver) + # end + # end + # + # server = TestServer.new([[:udp, '127.0.0.1', 2346]]) + # server.run + # class Server - # The default server interfaces + # The default server interfaces. DEFAULT_ENDPOINTS = [[:udp, "0.0.0.0", 53], [:tcp, "0.0.0.0", 53]] - # Instantiate a server with a block - # - # server = Server.new do - # match(/server.mydomain.com/, IN::A) do |transaction| - # transaction.respond!("1.2.3.4") - # end - # end + # Instantiate a server with a block. # + # @param endpoints [Array<(Symbol, String, Integer)>] The endpoints to listen on. + # @param origin [String] The default origin to resolve domains within. + # @param logger [Console::Logger] The logger to use. def initialize(endpoints = DEFAULT_ENDPOINTS, origin: '.', logger: Console.logger) @endpoints = endpoints @origin = origin @logger = logger end - # Records are relative to this origin: + # Records are relative to this origin. + # + # @return [String] attr_accessor :origin + # The logger to use. + # + # @return [Console::Logger] attr_accessor :logger # Give a name and a record type, try to match a rule and use it for processing the given arguments. + # + # @param name [String] The resource name. + # @param resource_class [Class] The requested resource class. + # @param transaction [Transaction] The transaction object. + # @abstract def process(name, resource_class, transaction) raise NotImplementedError.new end diff --git a/lib/async/dns/transaction.rb b/lib/async/dns/transaction.rb index 966cc51..290b4fc 100644 --- a/lib/async/dns/transaction.rb +++ b/lib/async/dns/transaction.rb @@ -153,7 +153,7 @@ def add(resources, options = {}) end end - # This function indicates that there was a failure to resolve the given question. The single argument must be an integer error code, typically given by the constants in {Resolv::DNS::RCode}. + # This function indicates that there was a failure to resolve the given question. The single argument must be an integer error code, typically given by the constants in `Resolv::DNS::RCode`. # # The easiest way to use this function it to simply supply a symbol. Here is a list of the most commonly used ones: #