docs: add documentation for various classes in app/logical.

app/logical/iqdb_client.rb

@@ -1,13 +1,21 @@
+# An API client for Danbooru's internal IQDB instance. Can add images, remove
+# images, and search for images in IQDB.
+#
+# @see https://github.com/danbooru/iqdb
 class IqdbClient
   class Error < StandardError; end
   attr_reader :iqdb_url, :http
 
+  # Create a new IQDB API client.
+  # @param iqdb_url [String] the base URL of the IQDB server
+  # @param http [Danbooru::Http] the HTTP client to use
   def initialize(iqdb_url: Danbooru.config.iqdb_url.to_s, http: Danbooru::Http.new)
     @iqdb_url = iqdb_url.chomp("/")
     @http = http
   end
 
   concerning :QueryMethods do
+    # Search for an image by file, URL, or post ID.
     def search(post_id: nil, file: nil, url: nil, image_url: nil, file_url: nil, similarity: 0.0, high_similarity: 65.0, limit: 20)
       limit = limit.to_i.clamp(1, 1000)
       similarity = similarity.to_f.clamp(0.0, 100.0)
@@ -37,6 +45,10 @@ class IqdbClient
       file.try(:close)
     end
 
+    # Download an URL to a file.
+    # @param url [String] the URL to download
+    # @param type [Symbol] the type of URL to download (:preview_url or full :image_url)
+    # @return [MediaFile] the downloaded file
     def download(url, type)
       strategy = Sources::Strategies.find(url)
       download_url = strategy.send(type)
@@ -44,8 +56,12 @@ class IqdbClient
       file
     end
 
-    def decorate_posts(json)
-      post_ids = json.map { |match| match["post_id"] }
+    # Transform the JSON returned by IQDB to add the full post data for each
+    # match.
+    # @param matches [Array<Hash>] the array of IQDB matches
+    # @return [Array<Hash>] the array of IQDB matches, with post data
+    def decorate_posts(matches)
+      post_ids = matches.map { |match| match["post_id"] }
       posts = Post.where(id: post_ids).group_by(&:id).transform_values(&:first)
 
       json.map do |match|
@@ -55,6 +71,8 @@ class IqdbClient
     end
   end
 
+  # Add a post to IQDB.
+  # @param post [Post] the post to add
   def add_post(post)
     return unless post.has_preview?
     preview_file = post.file(:preview)
@@ -62,20 +80,31 @@ class IqdbClient
   end
 
   concerning :HttpMethods do
+    # Search for an image in IQDB.
+    # @param file [File] the image to search
     def query(file, limit: 20)
       file = HTTP::FormData::File.new(file)
       request(:post, "query", form: { file: file }, params: { limit: limit })
     end
 
+    # Add a post to IQDB.
+    # @param post_id [Integer] the post to add
+    # @param file [File] the image to add
     def add(post_id, file)
       file = HTTP::FormData::File.new(file)
       request(:post, "images/#{post_id}", form: { file: file })
     end
 
+    # Remove an image from IQDB.
+    # @param post_id [Integer] the post to remove
     def remove(post_id)
       request(:delete, "images/#{post_id}")
     end
 
+    # Send a request to IQDB.
+    # @param method [String] the HTTP method
+    # @param url [String] the IQDB url
+    # @param options [Hash] the URL params to send
     def request(method, url, **options)
       return [] if iqdb_url.blank? # do nothing if iqdb isn't configured
       response = http.timeout(30).send(method, "#{iqdb_url}/#{url}", **options)