Hi,
Has anyone write code for RDoc I18n support described in the following
wiki page.
http://www.rubygarden.org/ruby?RDocI18n
If nobody hasn’t done it, I’ll implement a subset of that page. I 'll
use it for the document of my extension library.
–
KUBO Takehiro
KUBO Takehiro kubo@jiubao.org writes:
Hi,
Has anyone write code for RDoc I18n support described in the following
wiki page.
http://www.rubygarden.org/ruby?RDocI18nIf nobody hasn’t done it, I’ll implement a subset of that page. I 'll
use it for the document of my extension library.
I made a patch for it. The spec is different slightly.
http://www.jiubao.org/ruby-rdoc/
In addition, I made another patch for rdoc and will make 3 patches at
the next weekend.
Cheers
–
KUBO Takehiro
I need to understand this patch.
When we all talked about this (here on and ruby-core) a while back, the
consensus was that you can’t really work with a file that has multiple
encodings: if you’re editing with one encoding, it will mess up the
sections of the file that have another encoding. As I result, we didn’t
go ahead with RDoc support for conditional comments based on encoding.
Did we get it wrong? It would be wonderful if we could support multiple
languages, encodings, and character sets in the same comment blocks.
Confused of Dallas
On Sunday, Oct 19, 2003, at 00:36 US/Central, KUBO Takehiro wrote:
I made a patch for it. The spec is different slightly.
http://www.jiubao.org/ruby-rdoc/
I’ve added the alpha-list patch to the latest CVS.
Many thanks.
Dave
On Sunday, Oct 19, 2003, at 00:36 US/Central, KUBO Takehiro wrote:
In addition, I made another patch for rdoc and will make 3 patches at
the next weekend.
Dave Thomas dave@pragprog.com writes:
I made a patch for it. The spec is different slightly.
http://www.jiubao.org/ruby-rdoc/I need to understand this patch.
When we all talked about this (here on and ruby-core) a while back, the
consensus was that you can’t really work with a file that has multiple
encodings: if you’re editing with one encoding, it will mess up the
sections of the file that have another encoding. As I result, we didn’t
go ahead with RDoc support for conditional comments based on encoding.
Firstly, sorry I haven’t read the discussion. I subscribed to
ruby-talk about one year ago, but I was not interested in rdoc until
quite recently.
Secondly, you are right. IMHO, if multiple encoding consist of only
iso-8859-*, there would be no problem (in theory). But with Japanese
encoding (Shift_JIS or EUC-JP), it will mess up others. So the first
example of ‘automatic charset conversion’ is my mistake.
Thirdly, the second example of ‘automatic charset conversion’ is
usefull in some case. All comments are written in utf-8 and converted
to proper encoding on generateing html files. For example, older
browsers could not read utf-8, so I want to change the encoding to
EUC-JP. But it could be done for the html files which are generated by
rdoc. Hmm.
Did we get it wrong? It would be wonderful if we could support multiple
languages, encodings, and character sets in the same comment blocks.Confused of Dallas
Sorry.
On Sunday, Oct 19, 2003, at 00:36 US/Central, KUBO Takehiro wrote:
–
KUBO Takehiro
Is there a way that we can do external file support in rdoc? I was looking
at rdoc’s mechanisms (and then got sidetracked on other stuff) to support an
external documentation mechanism. It would look something like:
Then in an external file, you might do:
-austin
On Sun, 19 Oct 2003 23:27:41 +0900, Dave Thomas wrote:
On Sunday, Oct 19, 2003, at 00:36 US/Central, KUBO Takehiro wrote:
Did we get it wrong? It would be wonderful if we could support multiple
languages, encodings, and character sets in the same comment blocks.
–
austin ziegler * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.10.21
* 14.05.30
On the face of it, I’m not too keen on this kind of approach. The
philosophy of RDoc is make document transparent, and in the same source
file as the code.
We’ve all seen the problems that arise now when documentation is
separate from code, and the code changes. I’d like to try to avoid this.
Cheers
Dave
On Tuesday, Oct 21, 2003, at 13:08 US/Central, Austin Ziegler wrote:
:class: Foo
documentation for class Foo.
:method: Foo.bar
documentation for class method Foo.bar
:method: Foo#bar
documentation for instance method Foo#bar.
[edited because there’s two different discussions]
We’ve all seen the problems that arise now when documentation is
separate from code, and the code changes. I’d like to try to avoid
this.
In general, I agree. However, there was a conversation on ruby-talk
a few weeks ago (where I started looking at this) that suggested
that there are cases when the inline documentation is, well, too
much. There are cases when RDoc makes really good API documentation,
but doesn’t work as well when you’re reading the source itself. (The
complaint was specifically about methods that are really self-
documenting, such as #<=>.)
There’s also no “clean” way to have RDoc help document the use of
a library which may be different than documenting the pure API. This
may help with some of that.
:class: Foo
documentation for class Foo.
:method: Foo.bar
documentation for class method Foo.bar
:method: Foo#bar
documentation for instance method Foo#bar.
On the face of it, I’m not too keen on this kind of approach. The
philosophy of RDoc is make document transparent, and in the same
source file as the code.
I agree … but we already have a problem, and that’s multi-
lingual documentation. What I’m suggesting is a framework that
allows both multi-lingual and external documentation. RDoc already
merges documentation when it’s spread across multiple source files,
doesn’t it? Thus, if I put some documentation in the source file and
then more in the external file, the two would be merged into a
single documentation block.
-austin
On Wed, 22 Oct 2003 03:12:30 +0900, Dave Thomas wrote:
On Tuesday, Oct 21, 2003, at 13:08 US/Central, Austin Ziegler > wrote:
–
austin ziegler * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.10.21
* 16.04.31
In general, I agree. However, there was a conversation on ruby-talk
a few weeks ago (where I started looking at this) that suggested
that there are cases when the inline documentation is, well, too
much. There are cases when RDoc makes really good API documentation,
but doesn’t work as well when you’re reading the source itself. (The
complaint was specifically about methods that are really self-
documenting, such as #<=>.)
Would it be possible to come up with a specific example: I’m kinda slow
today, and I’m havign a hard time seeing this.
There’s also no “clean” way to have RDoc help document the use of
a library which may be different than documenting the pure API. This
may help with some of that.
Could the file or class-level comment be used for this?
I’m not trying to quell requests for change here: I’m just trying to
understand the need.
Cheers
Dave
On Tuesday, Oct 21, 2003, at 15:21 US/Central, Austin Ziegler wrote:
On Wed, 22 Oct 2003, Austin Ziegler wrote:
I was part of that conversation. I think I may have even started it if
it’s the one I’m thinking of.
I didn’t feel like RDoc itself was in some way in need of a change. I was
critiquing what I think is non-value-adding documentation such as:
def remove_from_list(element)
@list.remove(element)
end
Chad
[edited because there’s two different discussions]
On Wed, 22 Oct 2003 03:12:30 +0900, Dave Thomas wrote: # > We’ve all
seen the problems that arise now when documentation is # > separate from
code, and the code changes. I’d like to try to avoid # > this. #In general, I agree. However, there was a conversation on ruby-talk
a few weeks ago (where I started looking at this) that suggested # that
there are cases when the inline documentation is, well, too # much. There
are cases when RDoc makes really good API documentation, # but doesn’t
work as well when you’re reading the source itself. (The # complaint was
specifically about methods that are really self- # documenting, such as
#<=>.) #
I was part of that conversation. I think I may have even started it if
it’s the one I’m thinking of.
I think you were. I know that David Black was involved in the conversation,
too.
I didn’t feel like RDoc itself was in some way in need of a change. I
was critiquing what I think is non-value-adding documentation such as:Remove an element from the list
def remove_from_list(element)
@list.remove(element)
end
You’re right. If you have the code immediately available, then such
documentation is NVA. In API documentation, though, I disagree that it’s
NVA. I find it quite annoying to open an rdoc API and find that half of the
methods aren’t documented … until I open the code window and see that it
really is a simple method.
As I told Dave, though, there’s a problem with the fact that multi-lingual
documentation is next to impossible if there’s any chance of multiple
encodings. What I’ve proposed would solve that – but it would also allow
for the other item.
-austin
On Wed, 22 Oct 2003 10:16:10 +0900, Chad Fowler wrote:
On Wed, 22 Oct 2003, Austin Ziegler wrote:
–
austin ziegler * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.10.23
* 00.54.55
Hi –
I didn’t feel like RDoc itself was in some way in need of a change. I
was critiquing what I think is non-value-adding documentation such as:Remove an element from the list
def remove_from_list(element)
@list.remove(element)
endYou’re right. If you have the code immediately available, then such
documentation is NVA. In API documentation, though, I disagree that it’s
NVA. I find it quite annoying to open an rdoc API and find that half of the
methods aren’t documented … until I open the code window and see that it
really is a simple method.
But if it’s a really simple method, in the sense that its name says
everything that needs to be known about it, then isn’t it essentially
self-documenting, even if it just appears in a list? I guess I see it
as a kind of cascade: if the method name doesn’t suffice, then the
documentation function falls through to the comments.
I just think it’s a pity, in a language like Ruby where the code is so
expressive, to clutter up the source files beyond the absolutely
necessary.
David
On Thu, 23 Oct 2003, Austin Ziegler wrote:
On Wed, 22 Oct 2003 10:16:10 +0900, Chad Fowler wrote:
–
David Alan Black
home: dblack@superlink.net
work: blackdav@shu.edu
Web: http://pirate.shu.edu/~blackdav