Improve YARD comments and docs

Author: jgarber623

README.md

@@ -46,7 +46,7 @@ With indieweb-endpoints-ruby added to your project's `Gemfile` and installed, yo
 require 'indieweb/endpoints'
 
 IndieWeb::Endpoints.get('https://aaronparecki.com')
-#=> { authorization_endpoint: "https://aaronparecki.com/auth", micropub: "https://aaronparecki.com/micropub", microsub: "https://aperture.p3k.io/microsub/1", redirect_uri: nil, token_endpoint: "https://aaronparecki.com/auth/token", webmention: "https://webmention.io/aaronpk/webmention" }
+#=> { authorization_endpoint: "https://aaronparecki.com/auth", "indieauth-metadata": "https://aaronparecki.com/.well-known/oauth-authorization-server", micropub: "https://aaronparecki.com/micropub", microsub: "https://aperture.p3k.io/microsub/1", redirect_uri: nil, token_endpoint: "https://aaronparecki.com/auth/token", webmention: "https://webmention.io/aaronpk/webmention" }
 ```
 
 This example will search `https://aaronparecki.com` for valid IndieAuth, Micropub, and Webmention endpoints and return a `Hash` of results. Each key in the returned `Hash` will have a value of either a `String` representing a URL or `nil`. The `redirect_uri` key's value will be either an `Array` or `nil` since a given URL may register multiple callback URLs.

lib/indieweb/endpoints.rb

@@ -18,12 +18,15 @@ class HttpError < Error; end
     class InvalidURIError < Error; end
     class SSLError < Error; end
 
-    # Discover a URL's IndieAuth, Micropub, Microsub, and Webmention endpoints
+    # Discover a URL's IndieAuth, Micropub, Microsub, and Webmention endpoints.
     #
+    # Convenience method for {IndieWeb::Endpoints::Client#endpoints}.
+    #
+    # @example
     #   IndieWeb::Endpoints.get('https://aaronparecki.com')
     #
-    # @param url [String] an absolute URL
-    # @return [Hash{Symbol => String, Array, nil}]
+    # @param (see IndieWeb::Endpoints::Client#endpoints)
+    # @return (see IndieWeb::Endpoints::Client#endpoints)
     def self.get(url)
       Client.new(url).endpoints
     end

lib/indieweb/endpoints/client.rb

@@ -8,8 +8,9 @@ class Client
         user_agent: 'IndieWeb Endpoint Discovery (https://rubygems.org/gems/indieweb-endpoints)'
       }.freeze
 
-      # Create a new client with a URL to parse for IndieWeb endpoints
+      # Create a new client with a URL to parse for IndieWeb endpoints.
       #
+      # @example
       #   client = IndieWeb::Endpoints::Client.new('https://aaronparecki.com')
       #
       # @param url [String, HTTP::URI, #to_s] an absolute URL
@@ -25,17 +26,17 @@ def inspect
         %(#<#{self.class.name}:#{format('%#0x', object_id)} uri: "#{uri}">)
       end
 
-      # A Hash of the discovered IndieWeb endpoints from the provided URL
+      # A Hash of the discovered IndieWeb endpoints from the provided URL.
       #
       # @return [Hash{Symbol => String, Array, nil}]
       def endpoints
         @endpoints ||= Parser.new(response).results
       end
 
-      # The HTTP::Response object returned by the provided URL
+      # The +HTTP::Response+ object returned by the provided URL.
       #
       # @return [HTTP::Response]
-      # @raise [IndieWeb::Endpoints::HttpError]
+      # @raise [IndieWeb::Endpoints::HttpError, IndieWeb::Endpoints::SSLError]
       def response
         @response ||= HTTP.follow(max_hops: 20)
                           .headers(HTTP_HEADERS_OPTS)

lib/indieweb/endpoints/response_headers_parser.rb

@@ -10,7 +10,7 @@ def initialize(response)
         @uri = response.uri
       end
 
-      # @param headers [Symbol]
+      # @param identifier [Symbol]
       # @return [Array<String>, nil]
       def results_for(identifier)
         return unless parsed_headers.key?(identifier)