Inline markup

[drbrain]

RDoc's TomDoc support allows rdoc-style inline markup like:

*bold*
_italic_
+code+
<tt>longer code expression</tt>

It also has a note saying "you should not depend on it".

I would like a clarification on what (if any) inline markup TomDoc allows.

[tombell]

The philosophy behind TomDoc means it would never be rendered by anything as TomDoc comments are meant to be read by humans in the source file itself. However TomDoc is flexible and you can use which ever parts make sense for your projects. So if you would like to include minor inline markup you're free to do so.

[trans]

I would enjoin people to support code (backticks) as well if/when they do.

[mojombo]

There are really only two inline formats that I think are very useful:

1. code (I tend to use backticks for this e.g. Use String.size to get the size
2. bold (Asterisks are already used for this, even in plaintext)

For the benefit of automatic doc formatters, I could be convinced to add these to the spec. I almost don't think they're necessary though, as any reasonable plaintext solution will carry meaning even when not specifically formatted.

[trans]

While tomdoc'ing some code, it occurred to me that backticks could be useful for more than just indicating code, they could also be an elegant way to address issue #36. TomDoc parsers could look for backticks as a potential indication of return type. e.g.

# Public: Duplicate some text an arbitrary number of times.
#
# text  - The String to be duplicated.
# count - The Integer number of times to duplicate the text.
#
# Examples
#
#   multiplex('Tom', 4)
#   # => 'TomTomTomTom'
#
# Returns the duplicated `String`.

[sarahhodne]

I don't think the TomDoc spec really needs to specify the formatting at all. TomDoc is more about the structure than the formatting. If you want to use Markdown, use Markdown. RDoc? Textile? Use whatever you want.