Improve GFM code documentation

Created by: riyad

addresses questions that came up in #1232

app/helpers/gitlab_markdown_helper.rb

 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)