Expand and improve documentation

Author: jgarber623

README.md

@@ -12,6 +12,7 @@
 - Perform [endpoint discovery](https://www.w3.org/TR/webmention/#sender-discovers-receiver-webmention-endpoint) on mentioned URLs.
 - Send webmentions to one or more mentioned URLs (and optionally include a [vouch](https://indieweb.org/Vouch) URL).
 - Verify that a received webmention's source URL links to a target URL (and optionally verify that a vouch URL mentions the source URL's domain).
+- Supports Ruby 2.6 and newer.
 
 ## Getting Started
 

USAGE.md

@@ -15,9 +15,7 @@ target = "https://aaronpk.example/post/100" # A post on someone else's website
 response = Webmention.send_webmention(source, target)
 ```
 
-`Webmention.send_webmention` will return either a `Webmention::Response` or a `Webmention::ErrorResponse`. Instances of both classes respond to `ok?`. Building on the examples above:
-
-A `Webmention::ErrorResponse` may be returned when:
+`Webmention.send_webmention` will return either a `Webmention::Response` or a `Webmention::ErrorResponse`. Instances of both classes respond to `ok?`. Building on the examples above,  a `Webmention::ErrorResponse` may be returned when:
 
 1. The target URL does not advertise a Webmention endpoint.
 2. The request to the target URL raises an `HTTP::Error` or an `OpenSSL::SSL::SSLError`.
@@ -150,7 +148,4 @@ verification.vouch_mentions_source?
 
 webmention-client-ruby avoids raising exceptions when making HTTP requests. As noted above, a `Webmention::ErrorResponse` should be returned in cases where an HTTP request triggers an exception.
 
-When crawling the supplied URL, `Webmention.mentioned_urls` _may_ raise a `NoMethodError` if:
-
-- a `Webmention::ErrorResponse` is returned, or
-- the response is of an unsupported MIME type.
+When crawling the supplied URL, `Webmention.mentioned_urls` _may_ raise a `NoMethodError` if a `Webmention::ErrorResponse` is returned, or the response is of an unsupported MIME type.

lib/webmention.rb

@@ -22,12 +22,12 @@ module Webmention
   # Retrieve unique URLs mentioned by the provided URL.
   #
   # @example
-  #   Webmention.mentioned_urls('https://jgarber.example/posts/100')
+  #   Webmention.mentioned_urls("https://jgarber.example/posts/100")
   #
   # @param url [String, HTTP::URI, #to_s] An absolute URL.
   #
   # @raise [NoMethodError]
-  #   Raised when response is a Webmention::ErrorResponse or response is of an
+  #   Raised when response is an {ErrorResponse} or response is of an
   #   unsupported MIME type.
   #
   # @return [Array<String>]
@@ -38,14 +38,14 @@ def self.mentioned_urls(url)
   # Send a webmention from a source URL to a target URL.
   #
   # @example Send a webmention
-  #   source = 'https://jgarber.example/posts/100'
-  #   target = 'https://aaronpk.example/notes/1'
+  #   source = "https://jgarber.example/posts/100"
+  #   target = "https://aaronpk.example/notes/1"
   #   Webmention.send_webmention(source, target)
   #
   # @example Send a webmention with a vouch URL
-  #   source = 'https://jgarber.example/posts/100'
-  #   target = 'https://aaronpk.example/notes/1'
-  #   Webmention.send_webmention(source, target, vouch: 'https://tantek.example/notes/1')
+  #   source = "https://jgarber.example/posts/100"
+  #   target = "https://aaronpk.example/notes/1"
+  #   Webmention.send_webmention(source, target, vouch: "https://tantek.example/notes/1")
   #
   # @param source [String, HTTP::URI, #to_s]
   #   An absolute URL representing a source document.
@@ -55,22 +55,22 @@ def self.mentioned_urls(url)
   #   An absolute URL representing a document vouching for the source document.
   #   See https://indieweb.org/Vouch for additional details.
   #
-  # @return [Webmention::Response, Webmention::ErrorResponse]
+  # @return [Response, ErrorResponse]
   def self.send_webmention(source, target, vouch: nil)
     Client.new(source, vouch: vouch).send_webmention(target)
   end
 
   # Send webmentions from a source URL to multiple target URLs.
   #
   # @example Send multiple webmentions
-  #   source = 'https://jgarber.example/posts/100'
-  #   targets = ['https://aaronpk.example/notes/1', 'https://adactio.example/notes/1']
+  #   source = "https://jgarber.example/posts/100"
+  #   targets = ["https://aaronpk.example/notes/1", "https://adactio.example/notes/1"]
   #   Webmention.send_webmentions(source, targets)
   #
   # @example Send multiple webmentions with a vouch URL
-  #   source = 'https://jgarber.example/posts/100'
-  #   targets = ['https://aaronpk.example/notes/1', 'https://adactio.example/notes/1']
-  #   Webmention.send_webmentions(source, targets, vouch: 'https://tantek.example/notes/1')
+  #   source = "https://jgarber.example/posts/100"
+  #   targets = ["https://aaronpk.example/notes/1", "https://adactio.example/notes/1"]
+  #   Webmention.send_webmentions(source, targets, vouch: "https://tantek.example/notes/1")
   #
   # @param source [String, HTTP::URI, #to_s]
   #   An absolute URL representing a source document.
@@ -80,7 +80,7 @@ def self.send_webmention(source, target, vouch: nil)
   #   An absolute URL representing a document vouching for the source document.
   #   See https://indieweb.org/Vouch for additional details.
   #
-  # @return [Array<Webmention::Response, Webmention::ErrorResponse>]
+  # @return [Array<Response, ErrorResponse>]
   def self.send_webmentions(source, *targets, vouch: nil)
     Client.new(source, vouch: vouch).send_webmentions(*targets)
   end
@@ -89,7 +89,7 @@ def self.send_webmentions(source, *targets, vouch: nil)
   #
   # @param (see Webmention.send_webmention)
   #
-  # @raise (see Webmention::Client#mentioned_urls)
+  # @raise (see Client#mentioned_urls)
   #
   # @return [Boolean]
   def self.verify_webmention(source, target, vouch: nil)

lib/webmention/client.rb

@@ -9,32 +9,30 @@ class << self
       attr_reader :registered_parsers
     end
 
-    # @return [Webmention::Url]
+    # @return [Url]
     attr_reader :source_url
 
-    # @return [Webmention::Url]
+    # @return [Url]
     attr_reader :vouch_url
 
     # @api private
     def self.register_parser(klass)
       klass.mime_types.each { |mime_type| @registered_parsers[mime_type] = klass }
     end
 
-    # Create a new Webmention::Client.
+    # Create a new {Client}.
     #
     # @example
-    #   Webmention::Client.new('https://jgarber.example/posts/100')
+    #   Webmention::Client.new("https://jgarber.example/posts/100")
     #
     # @example
-    #   Webmention::Client.new('https://jgarber.example/posts/100', vouch: 'https://tantek.example/notes/1')
+    #   Webmention::Client.new("https://jgarber.example/posts/100", vouch: "https://tantek.example/notes/1")
     #
     # @param source [String, HTTP::URI, #to_s]
     #   An absolute URL representing a source document.
     # @param vouch [String, HTTP::URI, #to_s]
     #   An absolute URL representing a document vouching for the source document.
     #   See https://indieweb.org/Vouch for additional details.
-    #
-    # @return [Webmention::Client]
     def initialize(source, vouch: nil)
       @source_url = Url.new(source)
       @vouch_url = Url.new(vouch)
@@ -52,11 +50,11 @@ def inspect
     # Retrieve unique URLs mentioned by this client's source URL.
     #
     # @example
-    #   client = Webmention::Client.new('https://jgarber.example/posts/100')
+    #   client = Webmention::Client.new("https://jgarber.example/posts/100")
     #   client.mentioned_urls
     #
     # @raise [NoMethodError]
-    #   Raised when response is a Webmention::ErrorResponse or response is of an
+    #   Raised when response is an {ErrorResponse} or response is of an
     #   unsupported MIME type.
     #
     # @return [Array<String>]
@@ -78,13 +76,13 @@ def mentioned_urls
     # Send a webmention from this client's source URL to a target URL.
     #
     # @example
-    #   client = Webmention::Client.new('https://jgarber.example/posts/100')
-    #   client.send_webmention('https://aaronpk.example/notes/1')
+    #   client = Webmention::Client.new("https://jgarber.example/posts/100")
+    #   client.send_webmention("https://aaronpk.example/notes/1")
     #
     # @param target [String, HTTP::URI, #to_s]
     #   An absolute URL representing a target document.
     #
-    # @return [Webmention::Response, Webmention::ErrorResponse]
+    # @return [Response, ErrorResponse]
     def send_webmention(target)
       target_url = Url.new(target)
 
@@ -103,14 +101,14 @@ def send_webmention(target)
     # Send webmentions from this client's source URL to multiple target URLs.
     #
     # @example
-    #   client = Webmention::Client.new('https://jgarber.example/posts/100')
-    #   targets = ['https://aaronpk.example/notes/1', 'https://adactio.example/notes/1']
+    #   client = Webmention::Client.new("https://jgarber.example/posts/100")
+    #   targets = ["https://aaronpk.example/notes/1", "https://adactio.example/notes/1"]
     #   client.send_webmentions(targets)
     #
     # @param targets [Array<String, HTTP::URI, #to_s>]
     #   An array of absolute URLs representing multiple target documents.
     #
-    # @return [Array<Webmention::Response, Webmention::ErrorResponse>]
+    # @return [Array<Response, ErrorResponse>]
     def send_webmentions(*targets)
       targets.map { |target| send_webmention(target) }
     end
@@ -120,9 +118,9 @@ def send_webmentions(*targets)
     # @param target [String, HTTP::URI, #to_s]
     #   An absolute URL representing a target document.
     #
-    # @raise (see Webmention::Client#mentioned_urls)
+    # @raise (see Client#mentioned_urls)
     #
-    # @return [Webmention::Verification]
+    # @return [Verification]
     def verify_webmention(target)
       Verification.new(source_url, Url.new(target), vouch_url: vouch_url)
     end

lib/webmention/error_response.rb

@@ -5,20 +5,18 @@ class ErrorResponse
     # @return [String]
     attr_reader :message
 
-    # @return [Webmention::Request]
+    # @return [Request]
     attr_reader :request
 
-    # Create a new Webmention::ErrorResponse.
+    # Create a new {ErrorResponse}.
     #
     # Instances of this class represent HTTP requests that generated errors
     # (e.g. connection error, SSL error) or that could not locate a Webmention
-    # endpoint. The nature of the error is captured in the <code>#message</code>
-    # instance method.
+    # endpoint. The nature of the error is captured in the {#message} instance
+    # method.
     #
     # @param message [String]
-    # @param request [Webmention::Request]
-    #
-    # @return [Webmention::ErrorResponse]
+    # @param request [Request]
     def initialize(message, request)
       @message = message
       @request = request

lib/webmention/request.rb

@@ -2,8 +2,10 @@
 
 module Webmention
   class Request
-    # Defaults derived from Webmention specification examples.
+    # Set defaults derived from Webmention specification examples.
+    #
     # @see https://www.w3.org/TR/webmention/#limits-on-get-requests
+    #   W3C Webmention Recommendation § 4.2 Limits on GET requests
     HTTP_CLIENT_OPTS = {
       follow: {
         max_hops: 20,
@@ -32,23 +34,23 @@ class Request
     # Send an HTTP GET request to the supplied URL.
     #
     # @example
-    #   Request.get('https://jgarber.example/posts/100')
+    #   Webmention::Request.get("https://jgarber.example/posts/100")
     #
     # @param url [String]
     #
-    # @return [Webmention::Response, Webmention::ErrorResponse]
+    # @return [Response, ErrorResponse]
     def self.get(url)
       new(:get, url).perform
     end
 
     # Send an HTTP POST request with form-encoded data to the supplied URL.
     #
     # @example
-    #   Request.post(
-    #     'https://aaronpk.example/webmention',
-    #     source: 'https://jgarber.examples/posts/100',
-    #     target: 'https://aaronpk.example/notes/1',
-    #     vouch: 'https://tantek.example/notes/1'
+    #   Webmention::Request.post(
+    #     "https://aaronpk.example/webmention",
+    #     source: "https://jgarber.examples/posts/100",
+    #     target: "https://aaronpk.example/notes/1",
+    #     vouch: "https://tantek.example/notes/1"
     #   )
     #
     # @param url [String]
@@ -61,18 +63,16 @@ def self.get(url)
     #   An absolute URL representing a document vouching for the source document.
     #   See https://indieweb.org/Vouch for additional details.
     #
-    # @return [Webmention::Response, Webmention::ErrorResponse]
+    # @return [Response, ErrorResponse]
     def self.post(url, **options)
       new(:post, url, form: options.slice(:source, :target, :vouch)).perform
     end
 
-    # Create a new Webmention::Request.
+    # Create a new {Request}.
     #
     # @param method [Symbol]
     # @param url [String]
     # @param options [Hash{Symbol => String}]
-    #
-    # @return [Webmention::Request]
     def initialize(method, url, **options)
       @method = method.to_sym
       @uri = HTTP::URI.parse(url.to_s)
@@ -88,9 +88,9 @@ def inspect
     end
     # :nocov:
 
-    # Submit the Webmention::Request.
+    # Submit the {Request}.
     #
-    # @return [Webmention::Response, Webmention::ErrorResponse]
+    # @return [Response, ErrorResponse]
     def perform
       Response.new(client.request(method, uri, options), self)
     rescue HTTP::Error, OpenSSL::SSL::SSLError => e
@@ -99,6 +99,7 @@ def perform
 
     private
 
+    # @return [HTTP::Client]
     def client
       @client ||= HTTP::Client.new(HTTP_CLIENT_OPTS)
     end

lib/webmention/response.rb

@@ -4,7 +4,7 @@ module Webmention
   class Response
     extend Forwardable
 
-    # @return [Webmention::Request]
+    # @return [Request]
     attr_reader :request
 
     # @!method
@@ -31,16 +31,14 @@ class Response
     #   @return [HTTP::URI]
     def_delegator :@response, :uri
 
-    # Create a new Webmention::Response.
+    # Create a new {Response}.
     #
     # Instances of this class represent completed HTTP requests, the details
-    # of which may be accessed using the delegated <code>#code</code> and
-    # <code>#reason</code>) instance methods.
+    # of which may be accessed using the delegated {#code} and {#reason}
+    # instance methods.
     #
     # @param response [HTTP::Response]
-    # @param request [Webmention::Request]
-    #
-    # @return [Webmention::Response]
+    # @param request [Request]
     def initialize(response, request)
       @response = response
       @request = request

lib/webmention/url.rb

@@ -11,11 +11,9 @@ class Url
     #   @return [String]
     def_delegator :uri, :to_s
 
-    # Create a new Webmention::Url.
+    # Create a new {Url}.
     #
     # @param url [String, HTTP::URI, #to_s] An absolute URL.
-    #
-    # @return [Webmention::Url]
     def initialize(url)
       @uri = HTTP::URI.parse(url.to_s)
     end
@@ -28,7 +26,7 @@ def inspect
     end
     # :nocov:
 
-    # @return [Webmention::Response, Webmention::ErrorResponse]
+    # @return [Response, ErrorResponse]
     def response
       @response ||= Request.get(uri)
     end