added YARD documentation for most classes

Author: mackuba

lib/didkit/at_handles.rb

@@ -1,6 +1,11 @@
 require_relative 'errors'
 
 module DIDKit
+
+  #
+  # @private
+  #
+
   module AtHandles
 
     private

lib/didkit/did.rb

@@ -6,16 +6,52 @@
 require_relative 'resolver'
 
 module DIDKit
+
+  #
+  # Represents a DID identifier (account on the ATProto network). This class serves as an entry
+  # point to various lookup helpers. For convenience it can also be accessed as just `DID` without
+  # the `DIDKit::` prefix.
+  #
+  # @example Resolving a handle
+  #   did = DID.resolve_handle('bsky.app')
+  #
+
   class DID
     GENERIC_REGEXP = /\Adid\:\w+\:.+\z/
 
     include Requests
 
+    # Resolve a handle into a DID. Looks up the given ATProto domain handle using the DNS TXT method
+    # and the HTTP .well-known method and returns a DID if one is assigned using either of the methods.
+    #
+    # If a DID string or a {DID} object is passed, it simply returns that DID, so you can use this
+    # method to pass it an input string from the user which can be a DID or handle, without having to
+    # check which one it is.
+    #
+    # @param handle [String, DID] a domain handle (may start with an `@`) or a DID string
+    # @return [DID, nil] resolved DID if found, nil otherwise
+
     def self.resolve_handle(handle)
       Resolver.new.resolve_handle(handle)
     end
 
-    attr_reader :type, :did, :resolved_by
+    # @return [Symbol] DID type (`:plc` or `:web`)
+    attr_reader :type
+
+    # @return [String] DID identifier string
+    attr_reader :did
+
+    # @return [Symbol, nil] `:dns` or `:http` if the DID was looked up using one of those methods
+    attr_reader :resolved_by
+
+    alias to_s did
+
+
+    # Create a DID object from a DID string.
+    #
+    # @param did [String, DID] DID string or another DID object
+    # @param resolved_by [Symbol, nil] optionally, how the DID was looked up (`:dns` or `:http`)
+    # @raise [DIDError] when the DID format or type is invalid
 
     def initialize(did, resolved_by = nil)
       if did.is_a?(DID)
@@ -36,20 +72,39 @@ def initialize(did, resolved_by = nil)
       @resolved_by = resolved_by
     end
 
-    alias to_s did
+    # Returns or looks up the DID document with the DID's identity details from an appropriate source.
+    # This method caches the document in a local variable if it's called again.
+    #
+    # @return [Document] resolved DID document
 
     def document
       @document ||= get_document
     end
 
+    # Looks up the DID document with the DID's identity details from an appropriate source.
+    # @return [Document] resolved DID document
+
     def get_document
       Resolver.new.resolve_did(self)
     end
 
+    # Returns the first verified handle assigned to this DID.
+    #
+    # Looks up the domain handles assigned to this DID in its DID document, checks if they are
+    # verified (i.e. assigned correctly to this DID using DNS TXT or .well-known) and returns
+    # the first handle that validates correctly, or nil if none matches.
+    #
+    # @return [String, nil] verified handle domain, if found
+
     def get_verified_handle
       Resolver.new.get_verified_handle(document)
     end
 
+    # Fetches the PLC audit log (list of all previous operations) for a did:plc DID.
+    #
+    # @return [Array<PLCOperation>] list of PLC operations in the audit log
+    # @raise [DIDError] when the DID is not a did:plc
+
     def get_audit_log
       if @type == :plc
         PLCImporter.new.fetch_audit_log(self)
@@ -58,10 +113,23 @@ def get_audit_log
       end
     end
 
+    # Returns the domain portion of a did:web identifier.
+    #
+    # @return [String, nil] DID domain if the DID is a did:web, nil for did:plc
+
     def web_domain
       did.gsub(/^did\:web\:/, '') if type == :web
     end
 
+    # Checks the status of the account/repo on its own PDS using the `getRepoStatus` endpoint.
+    #
+    # @param request_options [Hash] request options to override
+    # @option request_options [Integer] :timeout request timeout (default: 15)
+    # @option request_options [Integer] :max_redirects maximum number of redirects to follow (default: 5)
+    #
+    # @return [Symbol, nil] `:active`, or returned inactive status, or `nil` if account is not found
+    # @raise [APIError] when the response is invalid
+
     def account_status(request_options = {})
       doc = self.document
       return nil if doc.pds_endpoint.nil?
@@ -91,14 +159,31 @@ def account_status(request_options = {})
       end
     end
 
+    # Checks if the account is seen as active on its own PDS, using the `getRepoStatus` endpoint.
+    # This is a helper which calls the {#account_status} method and checks if the status is `:active`.
+    #
+    # @return [Boolean] true if the returned status is active
+    # @raise [APIError] when the response is invalid
+
     def account_active?
       account_status == :active
     end
 
+    # Checks if the account exists its own PDS, using the `getRepoStatus` endpoint.
+    # This is a helper which calls the {#account_status} method and checks if the repo is found at all.
+    #
+    # @return [Boolean] true if the returned status is valid, false if repo is not found
+    # @raise [APIError] when the response is invalid
+
     def account_exists?
       account_status != nil
     end
 
+    # Compares the DID to another DID object or string.
+    #
+    # @param other [DID, String] other DID to compare with
+    # @return [Boolean] true if it's the same DID
+
     def ==(other)
       if other.is_a?(String)
         self.did == other

lib/didkit/document.rb

@@ -5,11 +5,39 @@
 require_relative 'services'
 
 module DIDKit
+
+  #
+  # Parsed DID document from a JSON file loaded from [plc.directory](https://plc.directory) or a did:web domain.
+  #
+  # Use {DID#document} or {Resolver#resolve_did} to fetch a DID document and return this object.
+  #
+
   class Document
     include AtHandles
     include Services
 
-    attr_reader :json, :did, :handles, :services
+    # @return [Hash] the complete JSON data of the DID document
+    attr_reader :json
+
+    # @return [DID] the DID that this document describes
+    attr_reader :did
+
+    # Returns a list of handles assigned to this DID in its DID document.
+    #
+    # Note: the handles aren't guaranteed to be verified (validated in the other direction).
+    # Use {#get_verified_handle} to find a handle that is correctly verified.
+    #
+    # @return [Array<String>]
+    attr_reader :handles
+
+    # @return [Array<ServiceRecords>] service records like PDS details assigned to the DID
+    attr_reader :services
+
+    # Creates a DID document object.
+    #
+    # @param did [DID] DID object
+    # @param json [Hash] DID document JSON
+    # @raise [FormatError] when required fields are missing or invalid.
 
     def initialize(did, json)
       raise FormatError, "Missing id field" if json['id'].nil?
@@ -23,10 +51,19 @@ def initialize(did, json)
       @handles = parse_also_known_as(json['alsoKnownAs'] || [])
     end
 
+    # Returns the first verified handle assigned to the DID.
+    #
+    # Looks up the domain handles assigned to this DID in the DID document, checks if they are
+    # verified (i.e. assigned correctly to this DID using DNS TXT or .well-known) and returns
+    # the first handle that validates correctly, or nil if none matches.
+    #
+    # @return [String, nil] verified handle domain, if found
+
     def get_verified_handle
       Resolver.new.get_verified_handle(self)
     end
 
+
     private
 
     def parse_services(service_data)

lib/didkit/errors.rb

@@ -1,24 +1,39 @@
 module DIDKit
-  class DIDError < StandardError
-  end
 
+  #
+  # Raised when an HTTP request returns a response with an error status.
+  #
   class APIError < StandardError
+
+    # @return [Net::HTTPResponse] the returned HTTP response
     attr_reader :response
 
+    # @param response [Net::HTTPResponse] the returned HTTP response
     def initialize(response)
       @response = response
       super("APIError: #{response}")
     end
 
+    # @return [Integer] HTTP status code
     def status
       response.code.to_i
     end
 
+    # @return [String] HTTP response body
     def body
       response.body
     end
   end
 
+  #
+  # Raised when a string is not a valid DID or not of the right type.
+  #
+  class DIDError < StandardError
+  end
+
+  #
+  # Raised when the loaded data has some missing or invalid fields.
+  #
   class FormatError < StandardError
   end
 end

lib/didkit/plc_operation.rb

@@ -6,11 +6,53 @@
 require_relative 'services'
 
 module DIDKit
+
+  #
+  # Represents a single operation of changing a specific DID's data in the [plc.directory](https://plc.directory)
+  # (e.g. changing assigned handles or migrating to a different PDS).
+  #
+
   class PLCOperation
     include AtHandles
     include Services
 
-    attr_reader :json, :did, :cid, :seq, :created_at, :type, :handles, :services
+    # @return [Hash] the JSON from which the operation is parsed
+    attr_reader :json
+
+    # @return [String] the DID which the operation concerns
+    attr_reader :did
+
+    # @return [String] CID (Content Identifier) of the operation
+    attr_reader :cid
+
+    # Returns a sequential number of the operation (only used in the new export API).
+    # @return [Integer, nil] sequential number of the operation
+    attr_reader :seq
+
+    # @return [Time] time when the operation was created
+    attr_reader :created_at
+
+    # Returns the `type` field of the operation (usually `"plc_operation"`).
+    # @return [String] the operation type
+    attr_reader :type
+
+    # Returns a list of handles assigned to the DID in this operation.
+    #
+    # Note: the handles aren't guaranteed to be verified (validated in the other direction).
+    # Use {DID#get_verified_handle} or {Document#get_verified_handle} to find a handle that is
+    # correctly verified.
+    #
+    # @return [Array<String>]
+    attr_reader :handles
+
+    # @return [Array<ServiceRecords>] service records like PDS details assigned to the DID
+    attr_reader :services
+
+
+    # Creates a PLCOperation object.
+    #
+    # @param json [Hash] operation JSON
+    # @raise [FormatError] when required fields are missing or invalid
 
     def initialize(json)
       @json = json

lib/didkit/requests.rb

@@ -5,6 +5,11 @@
 require_relative 'errors'
 
 module DIDKit
+
+  #
+  # @private
+  #
+
   module Requests
 
     private