Explain BlobViewer::Base#render_error

app/models/blob_viewer/base.rb

@@ -55,8 +55,23 @@ module BlobViewer
       too_large? && !absolutely_too_large?
     end
 
+    # This method is used on the server side to check whether we can attempt to
+    # render the blob at all. Human-readible error messages are found in the
+    # `BlobHelper#blob_render_error_reason` helper.
+    #
+    # This method does not and should not load the entire blob contents into
+    # memory, and should not be overridden to do so in order to validate the
+    # format of the blob.
+    #
+    # Prefer to implement a client-side viewer, where the JS component loads the
+    # binary from `blob_raw_url` and does its own format validation and error
+    # rendering, especially for potentially large binary formats.
     def render_error
       if server_side_but_stored_in_lfs?
+        # Files stored in LFS can only be rendered using a client-side viewer,
+        # since we do not want to read large amounts of data into memory on the
+        # server side. Client-side viewers use JS and can fetch the file from
+        # `blob_raw_url` using AJAX.
         :server_side_but_stored_in_lfs
       elsif override_max_size ? absolutely_too_large? : too_large?
         :too_large

app/models/blob_viewer/download.rb

@@ -9,6 +9,7 @@ module BlobViewer
     self.partial_name = 'download'
     self.binary = true
 
+    # We can always render the Download viewer, even if the blob is in LFS or too large.
     def render_error
       nil
     end