It may be a problem that fill-paragraph requires blank lines before
and after the paragraph to find a boundary of the paragraph. In ruby
code, such blank lines make code height-longer…
By the way, what is easier way to prepare documentation in some
natural languages, e.g., English and Japanese, with RDoc?
In the case of RD, I can extract RD from a.rb by
Hashes and arrays map keys to values. The method we are looking for
returns several values based on several keys.
I think I mentioned the following idea before, but I don’t remember
any response to it (and I’m kind of warming to it :-).
Namely: Enumerable#find_at
It has the following going for it, in my opinion:
it has “at” in it (see my last post for why I like “at” more than
verbs)
it makes a nice set with #find and #find_all:
a = %w{one two three four}
a.find {|e| e[0] == ?t} # “two”
a.find_all {|e| e.size > 3} # [“three”, “four”]
a.find_at(0,2) # [“one”, “three”]
it doesn’t already exist
David
Your reasons are good, but I don’t like it :->
Reason: given an index into a data structure, you don’t “find”
something, you get it directly. That’s what indices are all about.
That’s why I like “grab”: it connotes directness.
We’ve reached the “agree-to-disagree” point, but I find it interesting
to talk about anyway
My problem with grab is that it feels like its arguments are, in
grammatical terms, its direct objects (“grab these”) whereas in fact
what you’re grabbing is what’s stored at “these”. So to me its
“direct” quality is a little too direct.
I would prefer #values_of to #find_at, because #values is a great
choice which can’t be used for technical reasons.
By the way, what is easier way to prepare documentation in some
natural languages, e.g., English and Japanese, with RDoc?
In the case of RD, I can extract RD from a.rb by
% ruby -e ‘print if /^=begin/…/^=end/’ a.rb
and then I translate it into Japanese.
Would it be useful to have rdoc understand
=begin rdoc
…
=end
I’m not a big used of =begin/=end, so I’ll rely on the opinion of
others here.
GOTO Kentaro (in “Re: class documentation”) wrote:
[…]
It may be a problem that fill-paragraph requires blank lines before
and after the paragraph to find a boundary of the paragraph. In ruby
code, such blank lines make code height-longer…
[…]
I use “filladapt” with ruby-mode to edit comments, and it works much
better than the default fill-paragraph. It’s perfect for RDoc
documentation, too, because it understands indentation and lists.
Reason: given an index into a data structure, you don’t “find”
something, you get it directly. That’s what indices are all about.
That’s why I like “grab”: it connotes directness.
We’ve reached the “agree-to-disagree” point, but I find it interesting
to talk about anyway
My problem with grab is that it feels like its arguments are, in
grammatical terms, its direct objects (“grab these”) whereas in fact
what you’re grabbing is what’s stored at “these”. So to me its
“direct” quality is a little too direct.
Fair enough. Although the human mind soon resolves the issue by determining
the meaning based on context (it can only mean one thing, really), and then
noting what a clever choice of method name it is
I would prefer #values_of to #find_at, because #values is a great
choice which can’t be used for technical reasons.
How about #values_at ?
I can dig that. Quite nice, actually. Could hardly be any clearer, and is not
a handful to type or read.
Hashes and arrays map keys to values. The method we are looking for
returns several values based on several keys.
[…]
Reason: given an index into a data structure, you don’t “find”
something, you get it directly. That’s what indices are all about.
That’s why I like “grab”: it connotes directness.
[…]
My problem with grab is that it feels like its arguments are, in
grammatical terms, its direct objects (“grab these”) whereas in fact
what you’re grabbing is what’s stored at “these”. So to me its
“direct” quality is a little too direct.
What about
l,m,n = thing.lookup(x,y,z)
then? One is basically using these hashes/arrays like a directory,
a table, or even like a database of sorts…
By the way, what is easier way to prepare documentation in some
natural languages, e.g., English and Japanese, with RDoc?
In the case of RD, I can extract RD from a.rb by
% ruby -e ‘print if /^=begin/…/^=end/’ a.rb
and then I translate it into Japanese.
Would it be useful to have rdoc understand
=begin rdoc
…
=end
I’m not a big used of =begin/=end, so I’ll rely on the opinion of
others here.
I’m not a big used of =begin/=end, so I’ll rely on the opinion of
others here.
This would be quite helpful. I generally leave a space between the # and
the first character of the comment, but RDoc then goes and formats it as
monospaced space. Being able to write chunks of text without concern for #
placement would be very nice.
Hashes and arrays map keys to values. The method we are looking for
returns several values based on several keys.
[…]
Reason: given an index into a data structure, you don’t “find”
something, you get it directly. That’s what indices are all about.
That’s why I like “grab”: it connotes directness.
[…]
My problem with grab is that it feels like its arguments are, in
grammatical terms, its direct objects (“grab these”) whereas in fact
what you’re grabbing is what’s stored at “these”. So to me its
“direct” quality is a little too direct.
What about
l,m,n = thing.lookup(x,y,z)
then? One is basically using these hashes/arrays like a directory,
a table, or even like a database of sorts…
Actually, I think the mono space only kicks in if there is
an additional space before the text. For example:
=Header
This text is normal
this is mono for code
···
On Tue, Sep 24, 2002 at 05:14:44PM +0900, JamesBritt wrote:
Would it be useful to have rdoc understand
=begin rdoc
…
=end
I’m not a big used of =begin/=end, so I’ll rely on the opinion of
others here.
This would be quite helpful. I generally leave a space between the # and
the first character of the comment, but RDoc then goes and formats it as
monospaced space. Being able to write chunks of text without concern for #
placement would be very nice.
This would be quite helpful. I generally leave a space between the # and
the first character of the comment, but RDoc then goes and formats it as
monospaced space. Being able to write chunks of text without concern for #
placement would be very nice.
RDoc tries to work out the natural left margin for your text, and then
monospaced stuff indented past that. So having spaces after your #'s
is fine:
# This is normal
# test that wil be wrapped
# and this
# is verbatim text
# back to normal
I’m not a big used of =begin/=end, so I’ll rely on the opinion of
others here.
I would propably use them more if emacs ruby-mode didn’t take so long to
recognice & hilight them – seem to happen on opening a new file, but
rarely otherwise.
Still, if someone has used them in a library, it would be nice to be able
to use rdoc on it. This is not a big thing currently, but if the hinted-at
ri-rdoc marrige takes place, it would definitely be a must, especially
since quite a few existing thingies use them (rd-formatted, I guess).
From WordNet:
2: items selected from a population and used to test hypotheses
about the population [syn: {sample distribution}]
3: all or part of a natural object that is collected and
preserved as an example of its class
