How do I reference a param in the method description?

[kevgrig]

I reviewed the documentation but couldn't figure out how to reference an @param in the description of a method. Are backticks the only way? In the following example, I'd like to reference bar in the first sentence.

# This method takes `bar` and performs some transformations on it.
# 
# @param bar [String] the main input String
def foo(bar)

[lsegal]

Can you explain why you would need to reference a parameter? Typically references exist for linking, but docstrings + params are almost always displayed together. I suppose there is a world in which a docstring is displayed in a different place than the tags, though none of YARD's default templates do this, and I don't know of any customization in the wild that would, so I'm curious to know the use case.

tl;dr yes, using code markup in whatever markup syntax you're using should be sufficient.

[kevgrig]

I sometimes have very long and detailed function descriptions so I like to write a narrative structure in the function description using the parameters (this happens if param1 is X but if param2 is Y then that will happen, etc.). I think this is often much more logical than looking at each parameter independently and weaving it together in the mind. I might not reference all the parameters to avoid redundancy but often just the key parameters and how they interact (if they interact). I was thinking less of linking, but more just to have a logical reference so that it could be statically checked and avoid issues such as when a parameter is renamed and I might forget to update the parameter name in the method description. But no worries that this doesn't exist! Just double checking. Thanks for the consideration and thanks for YARD!