Mailinglist Archive: yast-devel (66 mails)

< Previous Next >
[yast-devel] Use YARD as code documentation tool?
Hi,

in the YCP Killer project we are currently working on transferring comments from YCP to Ruby. One part of that work is transferring documentation comments. This brings up the question of what documentation tool we want to use for YaST code in Ruby in general.

There are two main contenders:

* RDoc [1]
* YARD [2]

RDoc is a used since the very early days of Ruby. It is well known and its is somewhat a standard tool.

YARD is a newer, backward compatible with RDoc, but with more capabilities. It generates nicer documentation and its syntax is more similar to the current YaST one (it uses @tags). It can use widespread markup languages (like Markdown) instead of inventing its own wiki-style markup (like RDoc). It is extensible and it allows quick development by running a local server and seeing changes instantly (you just run "yard server --reload" and edit your files).

The killer feature of YARD is however the RubyDoc server [3]. There you can find documentation to many Ruby-based projects. You can add your own easily (which basically gives you a documentation hosting for free on a place expected by Ruby community). One great future is integration with GitHub, so you can see documentation of the development version of your project online immediately.

Because of all these features, most new Ruby projects choose YARD as their code documentation tool.

From the above, I guess it's obvious that I would like Ruby code in YaST to use YARD too. Do you agree with that, or do you have any better ideas?

[1] http://rdoc.sourceforge.net/
[2] http://yardoc.org/
[3] http://rubydoc.info/

--
David Majda
SUSE Studio developer
http://susestudio.com/
--
To unsubscribe, e-mail: yast-devel+unsubscribe@xxxxxxxxxxxx
To contact the owner, e-mail: yast-devel+owner@xxxxxxxxxxxx

< Previous Next >
List Navigation