diff --git a/app/helpers/gitlab_markdown_helper.rb b/app/helpers/gitlab_markdown_helper.rb
index 24bc3e85b9a..88e3473baf2 100644
--- a/app/helpers/gitlab_markdown_helper.rb
+++ b/app/helpers/gitlab_markdown_helper.rb
@@ -1,9 +1,18 @@
 module GitlabMarkdownHelper
+  # Replaces references (i.e. @abc, #123, !456, ...) in the text with links to
+  # the appropriate items in Gitlab.
+  #
+  # text          - the source text
+  # html_options  - extra options for the reference links as given to link_to
+  #
+  # note: reference links will only be generated if @project is set
+  #
+  # see Gitlab::Markdown for details on the supported syntax
   def gfm(text, html_options = {})
     return text if text.nil?
     return text if @project.nil?
 
-    # Extract pre blocks
+    # Extract pre blocks so they are not altered
     # from http://github.github.com/github-flavored-markdown/
     extractions = {}
     text.gsub!(%r{<pre>.*?</pre>|<code>.*?</code>}m) do |match|
@@ -25,7 +34,15 @@ module GitlabMarkdownHelper
     text.html_safe
   end
 
-  # circumvents nesting links, which will behave bad in browsers
+  # Use this in places where you would normally use link_to(gfm(...), ...).
+  #
+  # It solves a problem occurring with nested links (i.e.
+  # "<a>outer text <a>gfm ref</a> more outer text</a>"). This will not be
+  # interpreted as intended. Browsers will parse something like
+  # "<a>outer text </a><a>gfm ref</a> more outer text" (notice the last part is
+  # not linked any more). link_to_gfm corrects that. It wraps all parts to
+  # explicitly produce the correct linking behavior (i.e.
+  # "<a>outer text </a><a>gfm ref</a><a> more outer text</a>").
   def link_to_gfm(body, url, html_options = {})
     gfm_body = gfm(body, html_options)
 
diff --git a/lib/gitlab/markdown.rb b/lib/gitlab/markdown.rb
index d3daed91c32..75fa835d502 100644
--- a/lib/gitlab/markdown.rb
+++ b/lib/gitlab/markdown.rb
@@ -1,5 +1,14 @@
 module Gitlab
-  # Custom parsing for Gitlab-flavored Markdown
+  # Custom parser for Gitlab-flavored Markdown
+  #
+  # It replaces references in the text with links to the appropriate items in Gitlab.
+  #
+  # Supported reference formats are:
+  #   * @foo for team members
+  #   * #123 for issues
+  #   * !123 for merge requests
+  #   * $123 for snippets
+  #   * 123456 for commits
   #
   # Examples
   #
@@ -67,25 +76,25 @@ module Gitlab
     def reference_user(identifier)
       if user = @project.users.where(name: identifier).first
         member = @project.users_projects.where(user_id: user).first
-        link_to("@#{user.name}", project_team_member_path(@project, member), html_options.merge(class: "gfm gfm-team_member #{html_options[:class]}")) if member
+        link_to("@#{identifier}", project_team_member_path(@project, member), html_options.merge(class: "gfm gfm-team_member #{html_options[:class]}")) if member
       end
     end
 
     def reference_issue(identifier)
       if issue = @project.issues.where(id: identifier).first
-        link_to("##{issue.id}", project_issue_path(@project, issue), html_options.merge(title: "Issue: #{issue.title}", class: "gfm gfm-issue #{html_options[:class]}"))
+        link_to("##{identifier}", project_issue_path(@project, issue), html_options.merge(title: "Issue: #{issue.title}", class: "gfm gfm-issue #{html_options[:class]}"))
       end
     end
 
     def reference_merge_request(identifier)
       if merge_request = @project.merge_requests.where(id: identifier).first
-        link_to("!#{merge_request.id}", project_merge_request_path(@project, merge_request), html_options.merge(title: "Merge Request: #{merge_request.title}", class: "gfm gfm-merge_request #{html_options[:class]}"))
+        link_to("!#{identifier}", project_merge_request_path(@project, merge_request), html_options.merge(title: "Merge Request: #{merge_request.title}", class: "gfm gfm-merge_request #{html_options[:class]}"))
       end
     end
 
     def reference_snippet(identifier)
       if snippet = @project.snippets.where(id: identifier).first
-        link_to("$#{snippet.id}", project_snippet_path(@project, snippet), html_options.merge(title: "Snippet: #{snippet.title}", class: "gfm gfm-snippet #{html_options[:class]}"))
+        link_to("$#{identifier}", project_snippet_path(@project, snippet), html_options.merge(title: "Snippet: #{snippet.title}", class: "gfm gfm-snippet #{html_options[:class]}"))
       end
     end