Add some more code comments.

5 files changed, 20 insertions, 3 deletions

diff --git a/app/models/concerns/note_on_diff.rb b/app/models/concerns/note_on_diff.rb
index b511f33b8fa..6d8b9b76c84 100644
--- a/app/models/concerns/note_on_diff.rb
+++ b/app/models/concerns/note_on_diff.rb
@@ -31,6 +31,7 @@ module NoteOnDiff
     false
   end
 
+  # Returns an array of at most 16 highlighted lines above a diff note
   def truncated_diff_lines
     prev_match_line = nil
     prev_lines = []
diff --git a/app/models/merge_request.rb b/app/models/merge_request.rb
index 4624e9d36e9..ed99142902e 100644
--- a/app/models/merge_request.rb
+++ b/app/models/merge_request.rb
@@ -186,8 +186,9 @@ class MergeRequest < ActiveRecord::Base
   # This will not be the actual base commit if the target branch was merged into
   # the source branch after the merge request was created, but it is good enough
   # for the specific purpose of linking to a commit.
-  # It is not good enough for use in Gitlab::Git::DiffRefs, which need the
-  # true base commit.
+  # It is not good enough for use in `Gitlab::Git::DiffRefs`, which needs the
+  # true base commit, so we can't simply have `#diff_base_commit` fall back on
+  # this method.
   def likely_diff_base_commit
     first_commit.parent || first_commit
   end
diff --git a/lib/gitlab/diff/diff_refs.rb b/lib/gitlab/diff/diff_refs.rb
index 43489ae876b..8406ca4269c 100644
--- a/lib/gitlab/diff/diff_refs.rb
+++ b/lib/gitlab/diff/diff_refs.rb
@@ -18,6 +18,16 @@ module Gitlab
           head_sha == other.head_sha
       end
 
+      # There is only one case in which we will have `start_sha` and `head_sha`,
+      # but not `base_sha`, which is when a diff is generated between an
+      # orphaned branch and another branch, which means there _is_ no base, but
+      # we're still able to highlight it, and to create diff notes, which are
+      # the primary things `DiffRefs` are used for.
+      # `DiffRefs` are "complete" when they have `start_sha` and `head_sha`,
+      # because `base_sha` can always be derived from this, to return an actual
+      # sha, or `nil`.
+      # We have `base_sha` directly available on `DiffRefs` because it's faster#
+      # than having to look it up in the repo every time.
       def complete?
         start_sha && head_sha
       end
diff --git a/lib/gitlab/diff/line_mapper.rb b/lib/gitlab/diff/line_mapper.rb
index bde5b4eedaa..576a761423e 100644
--- a/lib/gitlab/diff/line_mapper.rb
+++ b/lib/gitlab/diff/line_mapper.rb
@@ -26,7 +26,7 @@ module Gitlab
         @diff_lines ||= @diff_file.diff_lines
       end
 
-      # Find old line number based on new line number.
+      # Find old/new line number based on its old/new counterpart line number.
       def map_line_number(from_line, from:, to:)
         # If no diff file could be found, the file wasn't changed, and the
         # mapped line number is the same as the specified line number.
diff --git a/lib/gitlab/diff/position.rb b/lib/gitlab/diff/position.rb
index 4eff71859c3..989fff8918e 100644
--- a/lib/gitlab/diff/position.rb
+++ b/lib/gitlab/diff/position.rb
@@ -28,6 +28,11 @@ module Gitlab
         end
       end
 
+      # `Gitlab::Diff::Position` objects are stored as serialized attributes in
+      # `DiffNote`, which use YAML to encode and decode objects.
+      # `#init_with` and `#encode_with` can be used to customize the en/decoding
+      # behavior. In this case, we override these to prevent memoized instance
+      # variables like `@diff_file` and `@diff_line` from being serialized.
       def init_with(coder)
         initialize(coder['attributes'])