How can I insert a bullet (<li>) element in Markdown-formatted YARD documentation

Question

I am using YARDoc with Markdown to document my Ruby code, and want to have an unordered list (HTML "bullets") in the documentation for a method. Here's what I have so far:

$ cat file.rb
class Foo
  # Returns "foo", which consists of the letters:
  # * f
  # * o
  # * o
  def method; "foo"; end
end

And I'm generating documentation using:

$ yard doc --markup markdown file.rb

But it does not generate HTML bullets, it treats the asterisks (*) as literal characters. The resulting doc/Foo.html file contains:

<span class="summary_desc"><div class='inline'><p>Returns &quot;foo&quot;,
which consists of the letters:
* f
* o
* o.</p>
</div></span>

How can I insert HTML bullets using Markdown in YARD? I essentially want each letter in the above output to be wrapped in <li>...</li>, and the list surrounded by a <ul> element.

Answer 1

I needed to have a blank line separating the first line of text and the start of the list:

$ cat file.rb 
class Foo
  # Returns "foo", which consists of the letters:
  #
  # * f
  # * o
  # * o
  def method; "foo"; end
end

which produces:

<div class="discussion">
  <p>Returns &quot;foo&quot;, which consists of the letters:</p>
  <ul>
    <li>f</li>
    <li>o</li>
    <li>o</li>
  </ul>
</div>

Answer 2

$ cat file.rb
class Foo
  # Returns "foo", which consists of the letters:

* f
* o
* o
^

  def method; "foo"; end
end

$ kramdown file.rb
<p>class Foo
  # Returns "foo", which consists of the letters:</p>

<ul>
  <li>f</li>
  <li>o</li>
  <li>o</li>
</ul>

<p>def method; "foo"; end
end</p>

http://kramdown.rubyforge.org/syntax.html#block-ials