Module: YARD::LinkStdlib::HtmlHelper

Defined in:
lib/yard/link_stdlib/html_helper.rb

Overview

A helper module to add to Templates::Template.extra_includes to handle linking stdlib references.

See Also:

Constant Summary collapse

INCLUDE_FILTER =

The Proc we pass to

Returns:

  • (Proc) 
proc do |options|
  HtmlHelper if options.format == :html
end

Instance Method Summary collapse

Instance Method Details

The only real meat of this whole gem - hook into object linking.

We link to the stdlib if:

  1. We didn’t link to anything else (local stuff take precedence).

  2. We can find a match for the reference.

Parameters:

  • obj (YARD::CodeObjects::Base) —

    The object to link to.

  • title (String?) (defaults to: nil) —

    Optional title to display the link as.

  • anchor (nil | ?) (defaults to: nil) —

    Not sure… not doc’d in YARD.

  • relative (Boolean) (defaults to: true) —

    Again, not sure… not doc’d in YARD, but seems like a boolean.

Returns:

  • (String) —

    The HTML source for the link.

See Also:



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/yard/link_stdlib/html_helper.rb', line 74

def link_object obj, title = nil, anchor = nil, relative = true
  # See what the super method can do...
  super_link = super

  # Bail out unless `super` returned a {String}, which I'm guessing would be
  # `nil`, but not sure.
  unless super_link.is_a?( String )
    LinkStdlib.dump "Object not linkable",
      obj: obj,
      super_link: super_link
    return super_link
  end

  LinkStdlib.dump "Object *may* be linkable!",
    obj: obj,
    super_link: super_link

  # if ( path = ObjectMap.current.data[ stdlib_key ] )
  if (url = ObjectMap.current.url_for super_link)
    LinkStdlib.dump "Matched stdlib link!",
      name: super_link,
      url: url
    
    # NOTE  `url` is **not** escaped because it may contains '#' followed
    #       by a fragment, and that needs to be preserved. At this point,
    #       I'm just assuming it's ready for use as-is.
    %(<a href="#{ url }">#{ CGI.escapeHTML super_link }</a>)

  else
    LinkStdlib.dump "Got nada.",
      super_link: super_link
    
    super_link

  end

end