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: [email protected]
To contact the owner, e-mail: [email protected]
