lib/nanoc/helpers/link_to.rb in nanoc-4.2.4 vs lib/nanoc/helpers/link_to.rb in nanoc-4.3.0

@@ -1,48 +1,16 @@
 module Nanoc::Helpers
-  # Contains functions for linking to items and item representations.
+  # @see http://nanoc.ws/doc/reference/helpers/#linkto
   module LinkTo
     require 'nanoc/helpers/html_escape'
     include Nanoc::Helpers::HTMLEscape
 
-    # Creates a HTML link to the given path or item representation, and with
-    # the given text. All attributes of the `a` element, including the `href`
-    # attribute, will be HTML-escaped; the contents of the `a` element, which
-    # can contain markup, will not be HTML-escaped. The HTML-escaping is done
-    # using {Nanoc::Helpers::HTMLEscape#html_escape}.
+    # @param [String] text
     #
-    # @param [String] text The visible link text
+    # @param [Hash] attributes
     #
-    # @param [String, Nanoc::Int::Item, Nanoc::Int::ItemRep] target The path/URL,
-    #   item or item representation that should be linked to
-    #
-    # @param [Hash] attributes A hash containing HTML attributes (e.g.
-    #   `rel`, `title`, …) that will be added to the link.
-    #
-    # @return [String] The link text
-    #
-    # @example Linking to a path
-    #
-    #   link_to('Blog', '/blog/')
-    #   # => '<a href="/blog/">Blog</a>'
-    #
-    # @example Linking to an item
-    #
-    #   about = @items.find { |i| i.identifier == '/about/' }
-    #   link_to('About Me', about)
-    #   # => '<a href="/about.html">About Me</a>'
-    #
-    # @example Linking to an item representation
-    #
-    #   about = @items.find { |i| i.identifier == '/about/' }
-    #   link_to('My vCard', about.rep(:vcard))
-    #   # => '<a href="/about.vcf">My vCard</a>'
-    #
-    # @example Linking with custom attributes
-    #
-    #   link_to('Blog', '/blog/', :title => 'My super cool blog')
-    #   # => '<a title="My super cool blog" href="/blog/">Blog</a>'
+    # @return [String]
     def link_to(text, target, attributes = {})
       # Find path
       path =
         case target
         when String
@@ -61,34 +29,15 @@
 
       # Create link
       "<a #{attributes}href=\"#{h path}\">#{text}</a>"
     end
 
-    # Creates a HTML link using {#link_to}, except when the linked item is
-    # the current one. In this case, a span element with class “active” and
-    # with the given text will be returned. The HTML-escaping rules for
-    # {#link_to} apply here as well.
+    # @param [String] text
     #
-    # @param [String] text The visible link text
+    # @param [Hash] attributes
     #
-    # @param [String, Nanoc::Int::Item, Nanoc::Int::ItemRep] target The path/URL,
-    #   item or item representation that should be linked to
-    #
-    # @param [Hash] attributes A hash containing HTML attributes (e.g.
-    #   `rel`, `title`, …) that will be added to the link.
-    #
-    # @return [String] The link text
-    #
-    # @example Linking to a different page
-    #
-    #   link_to_unless_current('Blog', '/blog/')
-    #   # => '<a href="/blog/">Blog</a>'
-    #
-    # @example Linking to the same page
-    #
-    #   link_to_unless_current('This Item', @item)
-    #   # => '<span class="active">This Item</span>'
+    # @return [String]
     def link_to_unless_current(text, target, attributes = {})
       # Find path
       path = target.is_a?(String) ? target : target.path
 
       if @item_rep && @item_rep.path == path
@@ -97,23 +46,10 @@
       else
         link_to(text, target, attributes)
       end
     end
 
-    # Returns the relative path from the current item to the given path or
-    # item representation. The returned path will not be HTML-escaped.
-    #
-    # @param [String, Nanoc::Int::Item, Nanoc::Int::ItemRep] target The path/URL,
-    #   item or item representation to which the relative path should be
-    #   generated
-    #
-    # @return [String] The relative path to the target
-    #
-    # @example
-    #
-    #   # if the current item's path is /foo/bar/
-    #   relative_path_to('/foo/qux/')
-    #   # => '../qux/'
+    # @return [String]
     def relative_path_to(target)
       require 'pathname'
 
       # Find path
       if target.is_a?(String)