Improve code comments

app/controllers/commontator/comments_controller.rb

@@ -213,24 +213,24 @@ def update_unread_status
                       .update(unread_comments: true)
       end
 
-      # Sets the flag for the comment icon in the navbar.
+      # Sets the flag for the comment icon in the navbar after a new comment
+      # was created.
       #
       # The flag is set if there are comments in the thread that the user
       # has not seen yet.
       #
       # This is only necessary for one specific edge case:
       # when the current user A has just created a new comment in a thread,
       # but in the meantime, another user B has created a comment in the same
-      # thread. User A will not see the comment icon in the navbar marked immediately
-      # (to be informed about the new comment by B), as we don't have websockets
-      # implemented. Instead, A will see the comment icon as soon as A has posted
-      # their own comment.
+      # thread. User A will not be informed immediately about the new comment
+      # by B since we don't have websockets implemented. Instead, A will be
+      # informed by an visual indicator as soon as A has posted their own comment.
       def activate_unread_comments_icon_if_necessary
         reader = Reader.find_by(user: current_user, thread: @commontator_thread)
 
-        # We only overwrite to true, not to false as the check here
-        # is not sufficient to determine whether a user has seen all comments
-        # also in other threads.
+        # We only overwrite to true, not to false as the check is not sufficient
+        # to determine whether a user has seen all comments (including those
+        # in possibly other threads).
         @update_icon = true if unseen_comments_in_current_thread?(reader)
       end
 

app/models/user.rb

@@ -550,12 +550,14 @@ def subscribed_commentable_media_with_comments
   end
 
   # Returns the media that the user has subscribed to and that have been
-  # commented on by somebody else (not by the current user).
-  # Note that media that have not been commented on by somebody else
-  # than the current user, are not returned (!).
+  # commented on by somebody else (not by the current user). The order is
+  # given by the time of the latest comment by somebody else.
   #
-  # For each medium, the latest comment by any user except the current one,
-  # the latest comment by any user (including the current one),
+  # Media that have not been commented on by somebody else than the current user,
+  # are not returned (!).
+  #
+  # For each medium, the latest comment by any user except the current user,
+  # the latest comment by any user (that might include the current user),
   # the thread and the medium itself are returned.
   def subscribed_media_with_latest_comments_not_by_creator
     media = subscribed_commentable_media_with_comments.map do |m|