search

lsegal / yard

YARD is a Ruby Documentation tool. The Y stands for "Yay!"
http://yardoc.org
MIT License
1.95k stars 398 forks source link

Markdown links in a method's description are not properly rendered or scrubbed in the method-summary list of a Class/Module #1550

Open postmodern opened 3 months ago

postmodern commented 3 months ago

I noticed this when reviewing the YARD API documentation using yard 0.9.36. Markdown named links (ex: [foo][1] ... [1]: ...) are not correctly rendered or scrubbed in the method-summary list for a Class/Method.

        #
        # [PowerShell unescapes][1] the characters in the data.
        #
        # [1]: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-7.2
        #
        # ...
        #
        def self.unescape(data)

As you can see, the [PowerShell unescapes][1] text is preserved in the method-list summary text at the top of the Class/Module.

yard_screenshot

Steps to reproduce

lib/test.rb:

module Test
  #
  # [Named link][1] here.
  #
  # [1]: https://example.com/
  #
  # @return [nil]
  #
  def self.test
  end
end

Gemfile:

source 'https://rubygems.org'
gem 'yard', '0.9.36'
gem 'redcarpet'
$ bundle exec yardoc --markup markdown
$ open doc/index.html

Actual Output

$ yardoc --markup markdown --debug
[debug]: Parsing ["{lib,app}/**/*.rb", "ext/**/*.{c,cc,cxx,cpp,rb}"] with `ruby` parser
[debug]: Parsing lib/test.rb
[debug]: Serializing to .yardoc/objects/root.dat
[debug]: Re-generating object ...
[debug]: Re-generating object Test...
[debug]: Generating asset js/jquery.js
[debug]: Serializing to doc/js/jquery.js
[debug]: Generating asset js/app.js
[debug]: Serializing to doc/js/app.js
[debug]: Generating asset js/full_list.js
[debug]: Serializing to doc/js/full_list.js
[debug]: Generating asset css/style.css
[debug]: Serializing to doc/css/style.css
[debug]: Generating asset css/common.css
[debug]: Serializing to doc/css/common.css
[debug]: Generating asset css/full_list.css
[debug]: Serializing to doc/css/full_list.css
[debug]: Generating asset class_list.html
[debug]: Serializing to doc/class_list.html
[debug]: Generating asset method_list.html
[debug]: Serializing to doc/method_list.html
[debug]: Generating asset file_list.html
[debug]: Serializing to doc/file_list.html
[debug]: Generating asset frames.html
[debug]: Serializing to doc/frames.html
[debug]: Serializing to doc/index.html
[debug]: Serializing to doc/_index.html
[debug]: Serializing to doc/top-level-namespace.html
[debug]: Serializing to doc/Test.html
Files:           1
Modules:         1 (    1 undocumented)
Classes:         0 (    0 undocumented)
Constants:       0 (    0 undocumented)
Attributes:      0 (    0 undocumented)
Methods:         1 (    0 undocumented)
 50.00% documented

yard_test_screenshot

Expected Output

Either render the method description with the markdown link,or render the method description as plain-text without the link.

Environment details:

postmodern commented 3 months ago

Wait, I get it... It's because YARD is taking the first line of the method description and rendering it. Since the [1]: ... is on the third line, the named YARD link is not able to render. Using a regular [Link name](https://...) link works. Feel free to close this.