Fix code docs

app/models/commit_range.rb

@@ -13,8 +13,7 @@
 #   range.to_param        # => {from: "f3f856029bc5f966c5a7ee24cf7efefdd20e6019^", to: "e86e1013709735be5bb767e2b228930c543f25ae"}
 #   range.to_s            # => "f3f85602..e86e1013"
 #
-#   # Assuming `project` is a Project with a repository containing both commits:
-#   range.project = project
+#   # Assuming the specified project has a repository containing both commits:
 #   range.valid_commits? # => true
 #
 class CommitRange
@@ -68,7 +67,7 @@ class CommitRange
 
     range_string.strip!
 
-    unless range_string.match(/\A#{PATTERN}\z/)
+    unless range_string =~ /\A#{PATTERN}\z/
       raise ArgumentError, "invalid CommitRange string format: #{range_string}"
     end
 
@@ -123,8 +122,6 @@ class CommitRange
 
   # Check if both the starting and ending commit IDs exist in a project's
   # repository
-  #
-  # project - An optional Project to check (default: `project`)
   def valid_commits?
     commit_start.present? && commit_end.present?
   end

lib/gitlab/markdown/abstract_reference_filter.rb

@@ -2,8 +2,8 @@ require 'gitlab/markdown'
 
 module Gitlab
   module Markdown
-    # Issues, Snippets and Merge Requests shares similar functionality in refernce filtering.
-    # All this functionality moved to this class
+    # Issues, Snippets, Merge Requests, Commits and Commit Ranges share
+    # similar functionality in refernce filtering.
     class AbstractReferenceFilter < ReferenceFilter
       include CrossProjectReference
 
@@ -26,16 +26,15 @@ module Gitlab
 
       # Public: Find references in text (like `!123` for merge requests)
       #
-      #   AnyReferenceFilter.references_in(text) do |match, object|
-      #     "<a href=...>PREFIX#{object}</a>"
+      #   AnyReferenceFilter.references_in(text) do |match, id, project_ref, matches|
+      #     object = find_object(project_ref, id)
+      #     "<a href=...>#{object.to_reference}</a>"
       #   end
       #
-      # PREFIX - symbol that detects reference (like ! for merge requests)
-      # object - reference object (snippet, merget request etc)
       # text - String text to search.
       #
-      # Yields the String match, the Integer referenced object ID, and an optional String
-      # of the external project reference.
+      # Yields the String match, the Integer referenced object ID, an optional String
+      # of the external project reference, and all of the matchdata.
       #
       # Returns a String replaced with the return of the block.
       def self.references_in(text)