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?

Yes Yard can document C files. Can you show a sample of your current C docs? What have you looked at so far towards the conversion? Are you sure you even need to convert anything, Yard is an extension of rdoc . . . have you simply tried to render your current docs using `yardoc`? — Neil Slater, Oct 03 '15 at 13:21
Yes I tryed `yardoc` in the main directory ( https://github.com/cedlemo/ruby-clangc ) but whithout success, I use rake rdoc in order to generate my documentation, you can see the Rake file in the link I give you. — cedlemo, Oct 03 '15 at 16:01

score 2 · Accepted Answer · edited May 23 '17 at 11:52

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.

Yard and C extension

1 Answers1