rdoc, darkfish, and the :call-seq: tag

问题:

I'm in the process of documenting a Ruby project with rdoc, and I discovered the darkfish rdoc formatter. I really like it, but the :call-seq: tag no longer works. Instead, it puts the literal string :call-seq: in the documentation and then formats the call sequence itself as a code block. I don't want to just take all of the :call-seq: blocks out of my code, since much of my documentation needs to refer to instance names and parameter names given in the :call-seq: block. Has anyone else had this problem? What should I do, and is there a workaround? I'm pretty sure the :call-seq: tag was working before when I was using the default formatter, but I can't be sure because I can't figure out how to go back to generating the original format (calling rdoc with no arguments except files generates darkfish output now, even if I delete the doc folder!) Does anyone know how to fix this?

回答1:

I strongly recommend moving from rdoc to YARD. It doesn't support the old call-seq itself, but instead it has tags and especially the @overload tag will superiorly replace call-seq. All the documentation on rubydoc.info is also generated using YARD.

Here's the example for @overload from the YARD documentation:

# @overload set(key, value)
#   Sets a value on key
#   @param [Symbol] key describe key param
#   @param [Object] value describe value param
# @overload set(value)
#   Sets a value on the default key `:foo`
#   @param [Object] value describe value param
def set(*args)
end