Yard and C extension

Question

I have a C ruby extension that I document with rdoc. There are both C files and ruby files that are parsed by rdoc.

Does yard can do the same and is there an "easy way", (I mean a commonly used way) to migrate from rdoc to yard?

Answer 1

As @Neil Slater said, Yard can parse rdoc style documentation with one exception which is the :call-seq tag from rdoc. Its equivalent is @overload from Yard. (see rdoc, darkfish, and the :call-seq: tag)

For me I used a Rake task in order to generate the rdoc documentation:

require "rdoc/task"

RDOC_FILES = FileList["README.rdoc", "ext/clangc/clangc.c", "ext/clangc/constants.c", "ext/clangc/class_Index.c", "ext/clangc/class_TranslationUnit.c", "lib/clangc.rb"]

Rake::RDocTask.new do |rd|
  rd.main = "README.rdoc"
  rd.rdoc_dir = "doc"
  rd.rdoc_files.include(RDOC_FILES)
end

I just have to launch rake rdoc

In order to use Yard instead, I just have to create a Rake task like this:

require "yard"
YARD_FILES = FileList["ext/clangc/clangc.c", "ext/clangc/class_Index.c", "ext/clangc/class_TranslationUnit.c", "lib/clangc.rb"]

YARD::Rake::YardocTask.new do |t|
  t.files   = YARD_FILES   # optional
  t.options = %w(-o yard_documentation --readme README.rdoc) # optional
end

Then I use rake yard. There still are some errors but the this is a good begining.