From: Dave Thomas <Dave@...>
Date: 2002-02-11T02:37:50+09:00
Subject: Re: Ruby Embedded Documentation

ts <decoux@moulon.inra.fr> writes:

> >>>>> "D" == Dave Thomas <Dave@PragmaticProgrammer.com> writes:
> 
> D> If you mean in the comments, then it automatically hyperlinks the
> D> #form, but currently not the ::form. Do you want me to add the ::form
> D> too? 
> 
>  Yes, I use the 2 sometimes in my latest example of bdb

> pigeon% more examples/replication/mc.rb
> #!/usr/bin/ruby
> $LOAD_PATH.unshift "../../src"
> 
> require 'bdb'
> require 'mutex_m'
> require 'socket'
> 
> module BDB
>    class MC < Env
>       extend Mutex_m
> 
>       ENVID = 1
> 
>       attr_accessor :sites, :priority, :timeout
> 
>       def self.new(home = nil, sites = 4, pri = 10, timeout = 2000000)
>          super(home, BDB::THREAD | BDB::CREATE | BDB::INIT_TRANSACTION,
>                "set_verb_replication" => 1, 
>                "specific" => [sites, pri, timeout]) 
>       end
> 
>       def initialize(*args)
>          @sites, @priority, @timeout = *args[-1]["specific"]
>          @mach = {}
>       end

I'm sleep deprived at the moment (Henry's in a "can't sleep, won't
sleep phase"), so forgive me. What part of this does RDoc not
currently handle?

>  Never expect that I'll put documentation, or comments, in my C
>  sources because if one day I do this these comments will be written
>  in french. I don't speak this strange language that you call
>  english. But I can write (try to write) a separate documentation,
>  like I do actually with rd

Fair enough, although at some point not too long from now RDoc will
support multiple-languages in the same file, allowing the user to
select the language that actually gets documented.

For me, RDoc is an interesting experiment in making a documentation
system that's as painless to use as possible. If people find it useful
too then that's wonderful, I also think that RD is a great tool. To
some extent, the important thing is that people write the necessary
documentation. The tool they choose to us is secondary.


Cheers


Dave