Add documentation to WithLockRetries class

Document WithLockRetries with details about how the class can be used in
application code.

lib/gitlab/database/with_lock_retries.rb

@@ -2,6 +2,11 @@
 
 module Gitlab
   module Database
+    # This class provides a way to automatically execute code that relies on acquiring a database lock in a way
+    # designed to minimize impact on a busy production database.
+    #
+    # A default timing configuration is provided that makes repeated attempts to acquire the necessary lock, with
+    # varying lock_timeout settings, and also serves to limit the maximum number of attempts.
     class WithLockRetries
       AttemptsExhaustedError = Class.new(StandardError)
 
@@ -65,6 +70,16 @@ module Gitlab
         @log_params = { method: 'with_lock_retries', class: klass.to_s }
       end
 
+      # Executes a block of code, retrying it whenever a database lock can't be acquired in time
+      #
+      # When a database lock can't be acquired, ActiveRecord throws ActiveRecord::LockWaitTimeout
+      # exception which we intercept to re-execute the block of code, until it finishes or we reach the
+      # max attempt limit. The default behavior when max attempts have been reached is to make a final attempt with the
+      # lock_timeout disabled, but this can be altered with the raise_on_exhaustion parameter.
+      #
+      # @see DEFAULT_TIMING_CONFIGURATION for the timings used when attempting a retry
+      # @param [Boolean] raise_on_exhaustion whether to raise `AttemptsExhaustedError` when exhausting max attempts
+      # @param [Proc] block of code that will be executed
       def run(raise_on_exhaustion: false, &block)
         raise 'no block given' unless block_given?