diff --git a/lib/gitlab/markdown/abstract_reference_filter.rb b/lib/gitlab/markdown/abstract_reference_filter.rb
index 0ec55c0207e136f4a301dc8365249968597e51e9..9488e980c086f22756e2f59eb6ec2fee3d9ff501 100644
--- a/lib/gitlab/markdown/abstract_reference_filter.rb
+++ b/lib/gitlab/markdown/abstract_reference_filter.rb
@@ -3,7 +3,7 @@ require 'gitlab/markdown'
 module Gitlab
   module Markdown
     # Issues, Merge Requests, Snippets, Commits and Commit Ranges share
-    # similar functionality in refernce filtering.
+    # similar functionality in reference filtering.
     class AbstractReferenceFilter < ReferenceFilter
       include CrossProjectReference
 
@@ -88,6 +88,8 @@ module Gitlab
       # to the referenced object's details page.
       #
       # text - String text to replace references in.
+      # pattern - Reference pattern to match against.
+      # link_text - Original content of the link being replaced.
       #
       # Returns a String with references replaced with links. All links
       # have `gfm` and `gfm-OBJECT_NAME` class names attached for styling.
@@ -98,7 +100,7 @@ module Gitlab
           if project && object = find_object(project, id)
             title = escape_once(object_link_title(object))
             klass = reference_class(object_sym)
-            
+
             data  = data_attribute(
               original:     link_text || match,
               project:      project.id,
diff --git a/lib/gitlab/markdown/reference_filter.rb b/lib/gitlab/markdown/reference_filter.rb
index 2597784c7aec39f19969ad165a562889f90d7d5c..b6d93e05ec7987ac198679902451b394c319ff86 100644
--- a/lib/gitlab/markdown/reference_filter.rb
+++ b/lib/gitlab/markdown/reference_filter.rb
@@ -122,6 +122,18 @@ module Gitlab
         doc
       end
 
+      # Iterate through the document's link nodes, yielding the current node's
+      # content if:
+      #
+      # * The `project` context value is present AND
+      # * The node's content matches `pattern`
+      #
+      # pattern - Regex pattern against which to match the node's content
+      #
+      # Yields the current node's String contents. The result of the block will
+      # replace the node and update the current document.
+      #
+      # Returns the updated Nokogiri::HTML::DocumentFragment object.
       def replace_link_nodes_with_text(pattern)
         return doc if project.nil?
 
@@ -148,6 +160,18 @@ module Gitlab
         doc
       end
 
+      # Iterate through the document's link nodes, yielding the current node's
+      # content if:
+      #
+      # * The `project` context value is present AND
+      # * The node's HREF matches `pattern`
+      #
+      # pattern - Regex pattern against which to match the node's HREF
+      #
+      # Yields the current node's String HREF and String content.
+      # The result of the block will replace the node and update the current document.
+      #
+      # Returns the updated Nokogiri::HTML::DocumentFragment object.
       def replace_link_nodes_with_href(pattern)
         return doc if project.nil?